/docs/MyDocs

Managign openshift cluster

==========================

    oc status

    openshift ex diagnostics

    oc get <type>

        Types: nodes, projects, pods

    oc describe <type> <id>                             - <id> is listed by 'oc get' command

    

 

    Web Console:

        https://192.168.12.201:8443/                    - important is https!

 

 

Standard Parameters

===================

 - Addressing

    -n <project>                                        - specifies project, otherthise current is used

    <type>/<name>                                       - specifies an object, like dc/apache, svc/mysql (space can be used instead of '/')

 

 - Misc

    --dry-run                                           - Don't execute actions actually (useful to view objects which would be populated by new-app, etc.)

 

 - Names / Labels

    --name <name>                                       - specifies the ID of newly created objects

    --display-name="<name>"                             - User-readable name

    --description="<description>"                       - Longer description

                                                        for the sake of simplictiy, in many cases the pod can be referenced by its dc (i.e. dc/apache instead of pod/apache-4-d45353)

    -l label=value                                      - set multiple labels on all created objects

    --selector="key=value"                              - restrict output only to the objects with the specified labels

    

 - Input/Output

    -o <format>                                         - specifies format to report information (json/yaml/wide)

    -f <file|->                                         - specifies file to read configuration from

 

 - Standard units

    cpu: #m                                             - 1000m is equal to 1 CPU core

    memory: #Mi/Gi                                      - MiB/GiB

 

 

Manage Resources

================

    oc get <type>[/name]                                - lists resources of the specified type (or just the named one) along with some details (oc get templates)

        --template '{{.spec.clusterIP}}'                - extracting specific information

        --template '{{index .spec.ports 0 "port"}}'     - accessing arrays is a bit tricky, this is quivalent to {{.spec.ports[0].port}}

 

    oc describe <obj>                                   - full specification of the specified resource and current status (in short human-readable form or fully in the specified format if -o given)

    oc export <obj>                                     - just object definition

    

    oc edit <obj>                                       - edit object specification in YaML/JSON

    oc patch <obj> -p '{json-structure-to-change}'      - edit object configuration, only specified attributes are changed. For instance, to alter nodes which are allowed to run the pod:

                                                                oc patch dc/apache -p '{"spec":{"template":{"spec":{"nodeSelector":{"master":"0"}}}}}'

 

    oc label <obj> key=value [--overwrite]              - tags objects

    

    

Deploying 

=========

 Most of the stuf is configured in YaML/JSON. Bellow are just a few commands to make standard actions.

 - See resources.txt for main options, view existing objects, and try to prototype with 'oc new-* -o json'

 - Even more stuff is possible directly with kubernets, see kubernetes.txt

 

 - Deploy and create objects                                    - 

    oc new-project <project_name>                               - creates new project / name-space

    oc new-app eboraas/apache:latest ENV=value                  - will get an image from dockerhub and create image-stream, dc, rc, pod and the service (environmental variables apply for all containers)

        -o json                                                 - the objects will be printed out in the requested format instead of being created

        -p <key>=<value>                                        - set parameters in templates

        -l <label>=<value>                                      - the labels will be assigned to all created objects

    oc new-app git://ufo.kit.edu/csa/adei.git                   - will build image from git repository

        --context-dir=''                                        - specify the directory with Dockerfile within Git repo

 

    oc create -f <[object-description]>                         - creates a list of objects from the file

    oc create <type>/<name>                                     - or just create just a simple object of the specified type (like new user or service-account without any permisions)

 

 - Editing Environment                                          - adjusting container environment after DC new application is created

    oc env <dc> VAR="value" VAR2="value"

 

 - Scaling

    oc scale <dc> --replicas=#                                  - scales the pod to specified number of replicas (scaling to 0 efficiently stopps the pod and associated services)

                                                                by scalling to 0 and then back to 1, it is possible to efficiently restart the pod.

                                                                    * For jobs/<name> it will change the number of replicas which have to complete, not the number of replicas executed

                                                                    in parallel. The later is changed with running 'scale' on corresponding RC.

    oc autoscale <dc> --min # --max # --cpu-percent=#           - will automatically scale number of running pods depending on POD CPU utilization which is computed with Cluster Metrics infrastructure

                                                                    * Cluster metrics should be properly configured.

                                                                    * HPS object is created and can be queried for status

 

 - Expose it to external users                                  - see more details in network.txt

    oc expose <svc/name> --hostname=<fqdn>                      - exposes the service for external users under the specified fqdn. FQDN is not required to belong to the configured OpenShift subdomain,

                                                                but can be arbitrary provided that the traffic is routed to the OpenShift masters.

                                                                    oc expose --name='apache-alias'  service/apache --hostname=katrin.kit.edu

 

 - Management & Automatic Updates

    oc set triggers <dc> --auto                                 - Enables automatic deployment rollout based on different conditions (by default 'dc' configuration change only)

        --from-image=<is> -c <container>                        - Monitors ImageStream and update the specified container when new image is pushed to is

 

    oc delete dc/<name> pod/<pod>                               - destroy deployment, rc, and running pods (but keeps service, ep)

    oc deploy dc/<name> --retry                                 - retry failed deployment

    oc deploy dc/<name> --cancel                                - cancel deployment which stuck

    oc rollback dc/<name>                                       - rollback to previous version (disables automatic updates, should be re-enabled with 'oc set triggers <dc> --auto'

    oc rollback dc/<name> --to-version=1                        - rollback to the specified version

 

 

Volumes & Configuration

=======================

 The customization of Docker containers is possible 

 - by setting enironmental variables and overriding the default command

 - by mounting temporary and persistent volumes

 - by s2i injection (which is normally used to inject interpreted sources in various web platforms)

 The special configuration objects: ConfigMaps and Secrets (secret is basically encrypted ConfigMap) is standard way to provide configuration. Both are key/value data stores which 

 can be either mounted as volumes (with each key represented as file) or referenced in other object definitions.

 

 - Config maps

    oc create cm/<name> <spec1> <spec2> ...

        --from-literal="key=value"                              - just specifying values on command line

        --from-file="[key=]path/file"                           - if key is omitted, the filename (without path) will be used as 'key'. And the file content as 'value'. Large files are OK.

        --from-file="path/dir"                                  - each file in the directory will be used to populate ConfigMap. The subdirectories seems not included.

    oc create secret generic <name> <specs>                     - generic secrets are created like CM

    oc create secret tls --cert="" --key=""                     - create secret with PEM-encoded key pair

    oc create secret docker-registry <name> <opts>              - secret used to generate ~/.dockercfg and allow pushing/pulling images from Docker registry

        --docker-username=user --docker-password=password --docker-email=email [--docker-server=string] [--from-literal=key1=value1]

 

 

Node Management

==============

 oc adm manage-node <nodes> --list-pods                         - list pods running on the specified node (or space-separated node list)

 oc adm manage-node <nodes> --schedulable=true/false            - temporary disables/enables placing new pods on the node (the already running pods will continue to run)

 oc adm manage-node <nodes> --evacuate                          - evacuate nodes from the specified nodes (nodes should be marked unschedulable or pods can be reschedulled back). 

                                                                There is no way to migrate pod to the specific node (unless all others are marked unschedulable)

    --pod-selector="app=apache"                                 - only evict the specified nodes

 

 

Debuging

========

 oc volumes pod/<pod>                                           - list volumes used by pod 

 oc export pod/apache-3-gnmq1 | grep nodeName                   - find where the pod is running

 

 oc get events                                                  - major events: failures, scheduling, deployments, builds, etc. Per-project.

 oc logs [-f] [--version=#] pod/<pod>                           - get logs (stdout) from running pod (or from failed deployment attempt),  -f starts 'watch'ing operation

 oc exec pod/<pod> [-c container] ls                            - run command in the pod (first container of pod by default, the pod should be running)

 oc rsh pod/<pod> [-c container] /bin/bash                      - run interactive command

 oc debug pod/<pod>                                             - this allows to start and debug failing container (i.e. when we can't connect to it with exec as it is failing)

 oc rsync <pod>:/src_path /local/dst_path                       - move data between local file system and pod

        --watch                                                 - continously running and synchronizes data upon changes

 

 

Templates

=========

 - List templates

    oc get is -n openshift                              - Standard image streams

    oc get templates -n openshift                       - Standard templates

 - Get template parameters

    oc process --parameters -n openshift mysql-persistent       - List parameters of the mysql template

 - Deploy from tempalte 

    oc process -n openshift -v MYSQL_USER=adei -v MYSQL_PASSWORD=adei -v MYSQL_ROOT_PASSWORD=ipepdv -v MYSQL_DATABASE=adei -v VOLUME_CAPACITY=1Gi -v MYSQL_VERSION=5.7 mysql-persistent | oc create -f -

 - Create templates

    oc export all --as-template=<name>                          - Generate template from current configuration

 

 

Secrets

=======