Developer Guide

When accessing the web console from a browser at <master_public_addr>:8443, you are automatically redirected to a login page.

Review the browser versions and operating systems that can be used to access the web console.

You can provide your login credentials on this page to obtain a token to make API calls. After logging in, you can navigate your projects using the web console.

You can authenticate from the command line using the CLI command oc login. You can get started with the CLI by running this command without any options:

$ oc login

The command’s interactive flow helps you establish a session to an OpenShift server with the provided credentials. If any information required to successfully log in to an OpenShift server is not provided, the command prompts for user input as required. The configuration is automatically saved and is then used for every subsequent command.

All configuration options for the oc login command, listed in the oc login --help command output, are optional. The following example shows usage with some common options:

$ oc login [-u=<username>] \
  [-p=<password>] \
  [-s=<server>] \
  [-n=<project>] \
  [--certificate-authority=</path/to/file.crt>|--insecure-skip-tls-verify]

The following table describes these common options:

$ oc login -s=<server>

$ oc login -u=<username> -p=<password>

$ oc login -u=<username> -p=<password> -n=<project>

$ oc login --certificate-authority=<path/to/file.crt>

$ oc login --insecure-skip-tls-verify

CLI configuration files allow you to easily manage multiple CLI profiles.

$ oc login -u system:admin -n default

A project allows a community of users to organize and manage their content in isolation from other communities.

If allowed by your cluster administrator, you can create a new project using the CLI or the web console.

To create a new project using the CLI:

$ oc new-project <project_name> \
    --description="<description>" --display-name="<display_name>"

For example:

$ oc new-project hello-openshift \
    --description="This is an example project to demonstrate OpenShift v3" \
    --display-name="Hello OpenShift"

When viewing projects, you are restricted to seeing only the projects you have access to view based on the authorization policy.

To view a list of projects:

$ oc get projects

You can change from the current project to a different project for CLI operations. The specified project is then used in all subsequent operations that manipulate project-scoped content:

$ oc project <project_name>

You can also use the web console to view and change between projects. After authenticating and logging in, you are presented with a list of projects that you have access to:

If you use the CLI to create a new project, you can then refresh the page in the browser to see the new project.

Selecting a project brings you to the project overview for that project.

The oc status command provides a high-level overview of the current project, with its components and their relationships. This command takes no argument:

$ oc status

You can filter the contents of a project page in the web console by using the labels of a resource. You can pick from a suggested label name and values, or type in your own. Multiple filters can be added. When multiple filters are applied, resources must match all of the filters to remain visible.

To filter by labels:

When you delete a project, the server updates the project status to Terminating from Active. The server then clears all content from a project that is Terminating before finally removing the project. While a project is in Terminating status, a user cannot add new content to the project.

To delete a project:

$ oc delete project <project_name>

When a person uses the command line or web console, their API token authenticates them to the OpenShift API. However, when a regular user’s credentials are not available, it is common for components to make API calls independently. For example:

Service accounts provide a flexible way to control API access without sharing a regular user’s credentials.

Every service account has an associated username that can be granted roles, just like a regular user. The username is derived from its project and name: system:serviceaccount:<project>:<name>

For example, to add the view role to the robot service account in the top-secret project:

$ oc policy add-role-to-user view system:serviceaccount:top-secret:robot

Every service account is also a member of two groups:

For example, to allow all service accounts in all projects to view resources in the top-secret project:

$ oc policy add-role-to-group view system:serviceaccounts -n top-secret

To allow all service accounts in the managers project to edit resources in the top-secret project:

$ oc policy add-role-to-group edit system:serviceaccounts:managers -n top-secret

Three service accounts are automatically created in every project:

All service accounts in a project are given the system:image-puller role, which allows pulling images from any image stream in the project using the internal Docker registry.

Service accounts are API objects that exist within each project. They can be created or deleted like any other API object.

$ more sa.json
{
  "apiVersion": "v1",
  "kind": "ServiceAccount",
  "metadata": {
    "name": "robot"
  }
}

$ oc create -f sa.json
serviceaccounts/robot

As soon as a service account is created, two secrets are automatically added to it:

These can be seen by describing the service account:

$ oc describe serviceaccount robot
Name:               robot
Labels:             <none>
Image pull secrets:	robot-dockercfg-624cx

Mountable secrets: 	robot-token-uzkbh
                   	robot-dockercfg-624cx

Tokens:            	robot-token-8bhpp
                   	robot-token-uzkbh

The system ensures that service accounts always have an API token and internal Docker registry credentials.

The generated API token and Docker registry credentials do not expire, but they can be revoked by deleting the secret. When the secret is deleted, a new one is automatically generated to take its place.

In addition to providing API credentials, a pod’s service account determines which secrets the pod is allowed to use.

Pods use secrets in two ways:

To allow a secret to be used as an image pull secret by a service account’s pods, run oc secrets add --for=pull serviceaccount/<serviceaccount-name> secret/<secret-name>

To allow a secret to be mounted by a service account’s pods, run oc secrets add --for=mount serviceaccount/<serviceaccount-name> secret/<secret-name>

This example creates and adds secrets to a service account:

$ oc secrets new secret-plans plan1.txt plan2.txt
secret/secret-plans

$ oc secrets new-dockercfg my-pull-secret \
    --docker-username=mastermind \
    --docker-password=12345 \
    --docker-email=mastermind@example.com
secret/my-pull-secret

$ oc secrets add serviceaccount/robot secret/secret-plans --for=mount

$ oc secrets add serviceaccount/robot secret/my-pull-secret --for=pull

$ oc describe serviceaccount robot
Name:               robot
Labels:             <none>
Image pull secrets:	robot-dockercfg-624cx
                   	my-pull-secret

Mountable secrets: 	robot-token-uzkbh
                   	robot-dockercfg-624cx
                   	secret-plans

Tokens:            	robot-token-8bhpp
                   	robot-token-uzkbh

When a pod is created, it specifies a service account (or uses the default service account), and is allowed to use that service account’s API credentials and referenced secrets.

A file containing an API token for a pod’s service account is automatically mounted at /var/run/secrets/kubernetes.io/serviceaccount/token

That token can be used to make API calls as the pod’s service account. This example calls the users/~ API to get information about the user identified by the token:

$ TOKEN="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)"

$ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
    "https://openshift.default.svc.cluster.local/oapi/v1/users/~" \
    -H "Authorization: Bearer $TOKEN"

{
  "kind": "User",
  "apiVersion": "v1",
  "metadata": {
    "name": "system:serviceaccount:top-secret:robot",
    "selfLink": "/oapi/v1/users/system:serviceaccount:top-secret:robot",
    "creationTimestamp": null
  },
  "identities": null,
  "groups": [
    "system:serviceaccounts",
    "system:serviceaccounts:top-secret"
  ]
}

The same token can be distributed to external applications that need to authenticate to the API.

Use oc describe secret <secret-name> to view a service account’s API token:

$ oc describe secret robot-token-uzkbh -n top-secret
Name:		robot-token-uzkbh
Labels:		<none>
Annotations:	kubernetes.io/service-account.name=robot,kubernetes.io/service-account.uid=49f19e2e-16c6-11e5-afdc-3c970e4b7ffe

Type:	kubernetes.io/service-account-token

Data
====
token:	eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...


$ oc login --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Logged into "https://server:8443" as "system:serviceaccount:top-secret:robot" using the token provided.

You don't have any projects. You can try to create a new project, by running

    $ oc new-project <projectname>

$ oc whoami
system:serviceaccount:top-secret:robot

You can create a new OpenShift application using the web console or by running the oc new-app command from the CLI. OpenShift creates a new application by specifying source code, images, or templates. The new-app command looks for images on the local Docker installation (if available), in a Docker registry, or an OpenShift image stream.

If you specify source code, new-app attempts to construct a build configuration that builds your source into a new application image. It also constructs a deployment configuration that deploys that new image, and a service to provide load balanced access to the deployment that is running your image.

You can create a new application using the oc new-app command from the CLI.

$ oc new-app .

$ oc new-app https://github.com/openshift/sti-ruby.git \
    --context-dir=2.0/test/puma-test-app

$ oc new-app https://github.com/openshift/ruby-hello-world.git#beta4

$ oc new-app /home/user/code/myapp --strategy=docker

$ oc new-app myproject/my-ruby~https://github.com/openshift/ruby-hello-world.git

$ oc new-app openshift/ruby-20-centos7:latest~/home/user/code/my-ruby-app

$ oc new-app mysql

$ oc new-app myregistry:5000/example/myimage

$ oc new-app my-stream:v1

$ oc create -f examples/sample-app/application-template-stibuild.json
$ oc new-app ruby-helloworld-sample

$ oc new-app -f examples/sample-app/application-template-stibuild.json

$ oc new-app ruby-helloworld-sample \
    -p ADMIN_USERNAME=admin,ADMIN_PASSWORD=mypassword

$ oc new-app openshift/postgresql-92-centos7 \
    -e POSTGRESQL_USER=user \
    -e POSTGRESQL_DATABASE=db \
    -e POSTGRESQL_PASSWORD=password

$ oc new-app https://github.com/openshift/ruby-hello-world -l name=hello-world

$ oc new-app https://github.com/openshift/ruby-hello-world -o json > myapp.json
$ vi myapp.json
$ oc create -f myapp.json

$ oc new-app https://github.com/openshift/ruby-hello-world --name=myapp

$ oc new-app https://github.com/openshift/ruby-hello-world -n myproject

$ oc new-app https://github.com/openshift/ruby-hello-world mysql

$ oc new-app nginx+mysql

$ oc new-app \
    ruby~https://github.com/openshift/ruby-hello-world \
    mysql \
    --group=ruby+mysql

You can also create applications using the web console:

A template describes a set of objects that can be parameterized and processed to produce a list of objects for creation by OpenShift. A template can be processed to create anything you have permission to create within a project, for example services, build configurations, and deployment configurations. A template may also define a set of labels to apply to every object defined in the template.

You can create a list of objects from a template using the CLI or, if a template has been uploaded to your project or the global template library, using the web console.

If you have a JSON or YAML file that defines a template, for example as seen in this example, you can upload the template to projects using the CLI. This saves the template to the project for repeated use by any user with appropriate access to that project. Instructions on writing your own templates are provided later in this topic.

To upload a template to your current project’s template library, pass the JSON or YAML file with the following command:

$ oc create -f <filename>

You can upload a template to a different project using the -n option with the name of the project:

$ oc create -f <filename> -n <project>

The template is now available for selection using the web console or the CLI.

To create the objects from an uploaded template using the web console:

You can use the CLI to process templates and use the configuration that is generated to create objects.

$ oc process -f <filename> -l name=otherLabel

$ oc process --parameters -f <filename>

$ oc process --parameters -n <project> <template_name>

$ oc process --parameters -n openshift rails-postgresql-example
NAME                         DESCRIPTION                                                                                              GENERATOR           VALUE
SOURCE_REPOSITORY_URL        The URL of the repository with your application source code                                                                  https://github.com/openshift/rails-ex.git
SOURCE_REPOSITORY_REF        Set this to a branch name, tag or other ref of your repository if you are not using the default branch
CONTEXT_DIR                  Set this to the relative path to your project if it is not in the root of your repository
APPLICATION_DOMAIN           The exposed hostname that will route to the Rails service                                                                    rails-postgresql-example.openshiftapps.com
GITHUB_WEBHOOK_SECRET        A secret string used to configure the GitHub webhook                                                     expression          [a-zA-Z0-9]{40}
SECRET_KEY_BASE              Your secret key for verifying the integrity of signed cookies                                            expression          [a-z0-9]{127}
APPLICATION_USER             The application user that is used within the sample application to authorize access on pages                                 openshift
APPLICATION_PASSWORD         The application password that is used within the sample application to authorize access on pages                             secret
DATABASE_SERVICE_NAME        Database service name                                                                                                        postgresql
POSTGRESQL_USER              database username                                                                                        expression          user[A-Z0-9]{3}
POSTGRESQL_PASSWORD          database password                                                                                        expression          [a-zA-Z0-9]{8}
POSTGRESQL_DATABASE          database name                                                                                                                root
POSTGRESQL_MAX_CONNECTIONS   database max connections                                                                                                     10
POSTGRESQL_SHARED_BUFFERS    database shared buffers                                                                                                      12MB

$ oc process -f <filename>

$ oc process <template_name>

$ cat <first_template> <second_template> | oc process -f -

$ oc process -f <filename> | oc create -f -

$ oc process <template> | oc create -f -

$ oc process -f my-rails-postgresql \
    -v POSTGRESQL_USER=bob,POSTGRESQL_DATABASE=mydatabase

$ oc process -f my-rails-postgresql \
    -v POSTGRESQL_USER=bob,POSTGRESQL_DATABASE=mydatabase \
    | oc create -f -

You can edit a template that has already been uploaded to your project by using the following command:

$ oc edit template <template>

OpenShift provides a number of default InstantApp templates to make it easy to quickly get started creating a new application for different languages. Templates are provided for Rails (Ruby), Django (Python), Node.js, CakePHP (PHP), and Dancer (Perl). Your cluster administrator should have created these templates in the default, global openshift project so you have access to them. You can list the available default InstantApp templates with:

$ oc get templates -n openshift

If they are not available, direct your cluster administrator to the First Steps topic.

By default, the templates build using a public source repository on GitHub that contains the necessary application code. In order to be able to modify the source and build your own version of the application, you must:

By doing this, the build configuration created by the template will now point to your fork of the application code, and you can modify the code and rebuild the application at will. A walkthrough of this process using the web console is provided in Getting Started for Developers: Web Console.

You can define new templates to make it easy to recreate all the objects of your application. The template will define the objects it creates along with some metadata to guide the creation of those objects.

{
  "kind": "Template",
  "apiVersion": "v1",
  "metadata": {
    "name": "cakephp-mysql-example",1
    "annotations": {
      "description": "An example CakePHP application with a MySQL database",2
      "tags": "instant-app,php,cakephp,mysql",3
      "iconClass": "icon-php"4
    }
  }
  ...
}

{
  "kind": "Template",
  "apiVersion": "v1",
  ...
  "labels": {
    "template": "cakephp-mysql-example"1
  }
  ...
}

{
  "kind": "Template",
  "apiVersion": "v1",
  ...
    {
      "kind": "BuildConfig",
      "apiVersion": "v1",
      "metadata": {
        "name": "cakephp-mysql-example",
        "annotations": {
          "description": "Defines how to build the application"
        }
      },
      "spec": {
        "source": {
          "type": "Git",
          "git": {
            "uri": "${SOURCE_REPOSITORY_URL}",1
            "ref": "${SOURCE_REPOSITORY_REF}"
          },
          "contextDir": "${CONTEXT_DIR}"
        },
      }
    }
   ...
 "parameters": [
    {
      "name": "SOURCE_REPOSITORY_URL",2
      "description": "The URL of the repository with your application source code",3
      "value": "https://github.com/openshift/cakephp-ex.git"4
      "required": true 5
    },
	{
      "name": "GITHUB_WEBHOOK_SECRET",
      "description": "A secret string used to configure the GitHub webhook",
      "generate": "expression",6
      "from": "[a-zA-Z0-9]{40}"7
    },
  ]
  ...
}

{
  "kind": "Template",
  "apiVersion": "v1",
  ...
  "objects": [
    {
      "kind": "Service",1
      "apiVersion": "v1",
      "metadata": {
        "name": "cakephp-mysql-example",
        "annotations": {
          "description": "Exposes and load balances the application pods"
        }
      },
      "spec": {
        "ports": [
          {
            "name": "web",
            "port": 8080,
            "targetPort": 8080
          }
        ],
        "selector": {
          "name": "cakephp-mysql-example"
        }
      }
    }
  ]
  ...
}

$ oc export all --as-template=<template_name>

A build is a process of creating runnable images to be used on OpenShift. There are three build strategies:

A build configuration describes a single build definition and a set of triggers for when a new build should be created.

A build configuration is defined by a BuildConfig, which is a REST object that can be used in a POST to the API server to create a new instance. The following example BuildConfig results in a new build every time a Docker image tag or the source code changes:

{
  "kind": "BuildConfig",
    "apiVersion": "v1",
    "metadata": {
      "name": "ruby-sample-build" 1
    },
  "spec": {
    "triggers": [ 2
      {
        "type": "GitHub",
        "github": {
          "secret": "secret101"
        }
      },
      {
        "type": "Generic",
        "generic": {
          "secret": "secret101"
        }
      },
      {
        "type": "ImageChange"
      }
    ],
    "source": { 3
      "type": "Git",
      "git": {
        "uri": "https://github.com/openshift/ruby-hello-world"
      }
    },
    "strategy": { 4
      "type": "Source",
      "sourceStrategy": {
        "from": {
          "kind": "ImageStreamTag",
          "name": "ruby-20-centos7:latest"
        }
      }
    },
    "output": { 5
      "to": {
        "kind": "ImageStreamTag",
        "name": "origin-ruby-sample:latest"
      }
    }
  }
}

The following options are specific to the S2I build strategy.

{
  "strategy": {
    "type": "Source",
    "sourceStrategy": {
      "from": {
        "kind": "ImageStreamTag",bas
        "name": "builder-image:latest" 1
      },
      "forcePull": true 2
    }
  }
}

{
  "strategy": {
    "type": "Source",
    "sourceStrategy": {
      "from": {
        "kind": "ImageStreamTag",
        "name": "incremental-image:latest" 1
      },
      "incremental": true 2
    }
  }
}

{
  "strategy": {
    "type": "Source",
    "sourceStrategy": {
      "from": {
        "kind": "ImageStreamTag",
        "name": "builder-image:latest"
      },
      "scripts": "http://somehost.com/scripts_directory" 1
    }
  }
}

{
  "sourceStrategy": {
    ...
    "env": [
      {
        "name": "DISABLE_ASSET_COMPILATION",
        "value": "true"
      }
    ]
  }
}

The following options are specific to the Docker build strategy.

strategy:
  type: "Docker"
  dockerStrategy:
    noCache: true

{
  "strategy": {
    "type": "Docker",
    "dockerStrategy": {
      "forcePull": true 1
    }
  }
}

{
  "dockerStrategy": {
    ...
    "env": [
      {
        "name": "HTTP_PROXY",
        "value": "http://myproxy.net:5187/"
      }
    ]
  }
}

The following options are specific to the Custom build strategy.

{
  "strategy": {
    "type": "Custom",
    "customStrategy": {
      "exposeDockerSocket": true
    }
  }
}

{
  "strategy": {
    "type": "Custom",
    "customStrategy": {
      "secrets": [
        {
          "secretSource": { 1
            "name": "secret1"
          },
          "mountPath": "/tmp/secret1" 2
        },
        {
          "secretSource": {
            "name": "secret2"
          },
          "mountPath": "/tmp/secret2"
        }
      ]
    }
  }
}

{
  "strategy": {
    "type": "Custom",
    "customStrategy": {
      "forcePull": true 1
    }
  }
}

{
  "customStrategy": {
    ...
    "env": [
      {
        "name": "HTTP_PROXY",
        "value": "http://myproxy.net:5187/"
      }
    ]
  }
}

If your Git repository can only be accessed using a proxy, you can define the proxy to use in the source section of the BuildConfig. You can configure both a HTTP and HTTPS proxy to use. Both fields are optional.

...
source:
  type: Git
  git:
    uri: "https://github.com/openshift/ruby-hello-world"
    httpProxy: http://proxy.example.com
    httpsProxy: https://proxy.example.com
...

$ ssh-keygen -t rsa -C "your_email@example.com"

When the BuildConfig.spec.source.type is Dockerfile, an inline Dockerfile is used as the build input, and no additional sources can be provided.

This source type is valid when the build strategy type is Docker or Custom.

The source definition is part of the spec section in the BuildConfig:

source:
  type: "Dockerfile"
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 1

When the BuildConfig.spec.source.type is Binary, the build will expect a binary as input, and an inline Dockerfile is optional.

The binary is generally assumed to be a tar, gzipped tar, or zip file depending on the strategy. For Docker builds, this is the build context and an optional Dockerfile may be specified to override any Dockerfile in the build context. For Source builds, this is assumed to be an archive as described above. For Source and Docker builds, if binary.asFile is set the build will receive a directory with a single file. The contextDir field may be used when an archive is provided. Custom builds will receive this binary as input on standard input (stdin).

A binary source potentially extracts content, in which case contextDir allows changing to a subdirectory within the content before the build executes.

The source definition is part of the spec section in the BuildConfig:

source:
  type: "Binary"
  binary: 1
    asFile: "webapp.war" 2
  contextDir: "app/dir" 3
  dockerfile: "FROM centos:7\nRUN yum install -y httpd" 4

Additional files can be provided to the build process via images. Input images are referenced in the same way the From and To image targets are defined. This means both docker images and image stream tags can be referenced. In conjunction with the image, you must provide one or more path pairs to indicate the path of the files/directories to copy out of the image and the destination to place them in the build context.

The source path can be any absolute path within the image specified. The destination must be a relative directory path. At build time, the image will be loaded and the indicated files/directories will be copied into the context directory of the build process. This is the same directory into which the source repository content (if any) is cloned.

Image inputs are specified in the source definition of the BuildConfig:

source:
  git:
    uri: https://github.com/openshift/ruby-hello-world.git
  images: 1
  - from: 2
      kind: ImageStreamTag
      name: myinputimage:latest
      namespace: mynamespace
    paths: 3
    - destinationDir: injected/dir 4
      sourcePath: /usr/lib/somefile.jar 5
  - from:
      kind: ImageStreamTag
      name: myotherinputimage:latest
      namespace: myothernamespace
    pullSecret: mysecret 6
    paths:
    - destinationDir: injected/dir
      sourcePath: /usr/lib/somefile.jar

In some scenarios operations performed by the build require credentials to access dependent resources, but it is undesirable for those credentials to be available in the final application image produced by the build.

For example, you are building a NodeJS application and you set up your private mirror for NodeJS modules. In order to download modules from that private mirror, you have to supply a custom .npmrc file for the build that contains a URL, username and password. For security reasons, you do not want to expose your credentials in the application image.

While this example describes NodeJS, you can use the same approach for adding SSL certificates into the /etc/ssl/certs directory, API keys or tokens, license files, etc.

$ oc secrets new secret-npmrc .npmrc=~/.npmrc

source:
  git:
    uri: https://github.com/openshift/nodejs-ex.git
  secrets:
    secret:
      name: secret-npmrc
  type: Git

$ oc new-build openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git --build-secret secret-npmrc

source:
  git:
    uri: https://github.com/openshift/nodejs-ex.git
  secrets:
    secret:
      name: secret-npmrc
    destinationDir: /etc
  type: Git

$ oc new-build openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git --build-secret “secret-npmrc:/etc”

Manually invoke a build using the following command:

$ oc start-build <BuildConfigName>

Re-run a build using the --from-build flag:

$ oc start-build --from-build=<buildName>

Specify the --follow flag to stream the build’s logs in stdout:

$ oc start-build <BuildConfigName> --follow

Manually cancel a build using the following command:

$ oc cancel-build <buildName>

To allow access to build logs, use the following command:

$ oc build-logs <buildName>

Log Verbosity

To enable more verbose output, pass the BUILD_LOGLEVEL environment variable as part of the sourceStrategy or dockerStrategy in a BuildConfig:

{
  "sourceStrategy": {
    ...
    "env": [
      {
        "name": "BUILD_LOGLEVEL",
        "value": "2" 1
      }
    ]
  }
}

Available log levels for Source builds are as follows:

The source code location is one of the required parameters for the BuildConfig. The build uses this location and fetches the source code that is later built. The source code location definition is part of the spec section in the BuildConfig:

{
  "source" : {
    "type" : "Git", 1
    "git" : { 2
      "uri": "https://github.com/openshift/ruby-hello-world"
    },
    "contextDir": "app/dir", 3
  },
}

When defining a BuildConfig, you can define triggers to control the circumstances in which the BuildConfig should be run. The following build triggers are available:

{
  "type": "GitHub",
  "github": {
    "secret": "secret101"
  }
}

http://<openshift_api_host:port>/osapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

{
  "type": "Generic",
  "generic": {
    "secret": "secret101"
  }
}

http://<openshift_api_host:port>/osapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

{
  type: 'git',
  git: {
    uri: '<url to git repository>',
    ref: '<optional git reference>',
    commit: '<commit hash identifying a specific git commit>',
    author: {
      name: '<author name>',
      email: '<author e-mail>',
    },
    committer: {
      name: '<committer name>',
      email: '<committer e-mail>',
    },
    message: '<commit message>'
  }
}

$ oc describe bc <name>

{
  "strategy": {
    "type": "Source",
    "sourceStrategy": {
      "from": {
        "kind": "DockerImage",
        "name": "172.30.17.3:5001/mynamespace/ruby-20-centos7:immutableid"
      }
    }
  }
}

{
  "type": "ConfigChange"
}

Supply the .dockercfg file with valid Docker Registry credentials in order to push the output image into a private Docker Registry or pull the builder image from the private Docker Registry that requires authentication. For the OpenShift Docker Registry, you don’t have to do this because secrets are generated automatically for you by OpenShift.

The .dockercfg JSON file is found in your home directory by default and has the following format:

{
	"https://index.docker.io/v1/": { 1
		"auth": "YWRfbGzhcGU6R2labnRib21ifTE=", 2
		"email": "user@example.com" 3
	}
}

You can define multiple Docker registry entries in this file. Alternatively, you can also add authentication entries to this file by running the docker login command. The file will be created if it does not exist. Kubernetes provides secret, which are used to store your configuration and passwords.

A deployment in OpenShift is a replication controller based on a user defined template called a deployment configuration. Deployments are created manually or in response to triggered events.

The deployment system provides:

The deployment configuration contains a version number that is incremented each time a new deployment is created from that configuration. In addition, the cause of the last deployment is added to the configuration.

A deployment configuration consists of the following key parts:

Deployment configurations are deploymentConfig OpenShift API resources which can be managed with the oc command like any other resource. The following is an example of a deploymentConfig resource:

{
  "kind": "DeploymentConfig",
  "apiVersion": "v1",
  "metadata": {
    "name": "frontend"
  },
  "spec": {
    "template": { 1
      "metadata": {
        "labels": {
          "name": "frontend"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "helloworld",
            "image": "openshift/origin-ruby-sample",
            "ports": [
              {
                "containerPort": 8080,
                "protocol": "TCP"
              }
            ]
          }
        ]
      }
    }
    "replicas": 5, 2
    "selector": {
      "name": "frontend"
    },
    "triggers": [
      {
        "type": "ConfigChange" 3
      },
      {
        "type": "ImageChange", 4
        "imageChangeParams": {
          "automatic": true,
          "containerNames": [
            "helloworld"
          ],
          "from": {
            "kind": "ImageStreamTag",
            "name": "origin-ruby-sample:latest"
          }
        }
      }
    ],
    "strategy": { 5
      "type": "Rolling"
    }
  }
}

To start a new deployment manually:

$ oc deploy <deployment_config> --latest

To get basic information about recent deployments:

$ oc deploy <deployment_config>

This will show details about the latest and recent deployments, including any currently running deployment.

For more detailed information about a deployment configuration and the latest deployment:

$ oc describe dc <deployment_config>

To cancel a running or stuck deployment:

$ oc deploy <deployment_config> --cancel

To retry the last failed deployment:

$ oc deploy <deployment_config> --retry

If the last deployment didn’t fail, the command will display a message and the deployment will not be retried.

Rollbacks revert an application back to a previous deployment and can be performed using the REST API or the CLI.

To rollback to the last successful deployment:

$ oc rollback <deployment_config>

The deployment configuration’s template will be reverted to match the deployment specified in the rollback command, and a new deployment will be started.

Image change triggers on the deployment configuration are disabled as part of the rollback to prevent unwanted deployments soon after the rollback is complete. To re-enable the image change triggers:

$ oc deploy <deployment_config> --enable-triggers

To roll back to a specific version:

$ oc rollback <deployment_config> --to-version=1

To see what the rollback would look like without performing the rollback:

$ oc rollback <deployment_config> --dry-run

A deployment configuration can contain triggers, which drive the creation of new deployments in response to events, both inside and outside OpenShift.

"triggers": [
  {
    "type": "ConfigChange"
  }
]

"triggers": [
  {
    "type": "ImageChange",
    "imageChangeParams": {
      "automatic": true, 1
      "from": {
        "kind": "ImageStreamTag",
        "name": "origin-ruby-sample:latest"
      },
      "containerNames": [
        "helloworld"
      ]
    }
  }
]

A deployment strategy determines the deployment process, and is defined by the deployment configuration. Each application has different requirements for availability (and other considerations) during deployments. OpenShift provides strategies to support a variety of deployment scenarios.

A deployment strategy uses readiness checks to determine if a new pod is ready for use. If a readiness check fails, the deployment is stopped.

The Rolling strategy is the default strategy used if no strategy is specified on a deployment configuration.

"strategy": {
  "type": "Rolling",
  "rollingParams": {
    "timeoutSeconds": 120, 1
    "maxSurge": "20%", 2
    "maxUnavailable": "10%" 3
    "pre": {}, 4
    "post": {}
  }
}

"strategy": {
  "type": "Recreate",
  "recreateParams": { 1
    "pre": {}, 2
    "post": {}
  }
}

"strategy": {
  "type": "Custom",
  "customParams": {
    "image": "organization/strategy",
    "command": ["command", "arg1"],
    "environment": [
      {
        "name": "ENV_1",
        "value": "VALUE_1"
      }
    ]
  }
}

The Recreate and Rolling strategies support lifecycle hooks, which allow behavior to be injected into the deployment process at predefined points within the strategy:

The following is an example of a "pre" lifecycle hook:

"pre": {
  "failurePolicy": "Abort",
  "execNewPod": {} 1
}

Every hook has a failurePolicy, which defines the action the strategy should take when a hook failure is encountered:

Hooks have a type-specific field that describes how to execute the hook. Currently pod-based hooks are the only supported hook type, specified by the execNewPod field.

{
  "kind": "DeploymentConfig",
  "apiVersion": "v1",
  "metadata": {
    "name": "frontend"
  },
  "spec": {
    "template": {
      "metadata": {
        "labels": {
          "name": "frontend"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "helloworld",
            "image": "openshift/origin-ruby-sample"
          }
        ]
      }
    }
    "replicas": 5,
    "selector": {
      "name": "frontend"
    },
    "strategy": {
      "type": "Rolling",
      "rollingParams": {
        "pre": {
          "failurePolicy": "Abort",
          "execNewPod": {
            "containerName": "helloworld", 1
            "command": [ 2
              "/usr/bin/command", "arg1", "arg2"
            ],
            "env": [ 3
              {
                "name": "CUSTOM_VAR1",
                "value": "custom_value1"
              }
            ]
          }
        }
      }
    }
  }
}

A deployment is completed by a pod that consumes resources (memory and cpu) on a node. By default, pods consume unbounded node resources. However, if a project specifies default container limits, then pods consume resources up to those limits. Another way to limit resource use is to specify resource limits as part of the deployment strategy. In the following example, each of resources, cpu, and memory is optional.

{
  "type": "Recreate",
  "resources": {
    "limits": {
      "cpu": "100m", 1
      "memory": "256Mi" 2
    }
  },
}

Deployment resources can be used with the Recreate, Rolling, or Custom deployment strategies.

In addition to rollbacks, you can exercise fine-grained control over the number of replicas by using the oc scale command. For example, the following command sets the replicas in the deployment configuration frontend to 3.

$ oc scale dc frontend --replicas=3

The number of replicas eventually propagates to the desired and current state of the deployment configured by the deployment configuration frontend.

An OpenShift route exposes a service at a host name, like www.example.com, so that external clients can reach it by name.

DNS resolution for a host name is handled separately from routing; your administrator may have configured a cloud domain that will always correctly resolve to the OpenShift router, or if using an unrelated host name you may need to modify its DNS records independently to resolve to the router.

Tooling for creating routes is developing. In the web console, they are displayed but there is not yet a method to create them. Using the CLI, you currently can create only an unsecured route:

$ oc expose service/<name> --hostname=<www.example.com>

The new route inherits the name from the service unless you specify one.

apiVersion: v1
kind: Route
metadata:
  name: route-name
spec:
  host: www.example.com
  to:
    kind: Service
    name: service-name

Unsecured routes are the default configuration, and are therefore the simplest to set up. However, secured routes offer security for connections to remain private. To create a secured HTTPS route encrypted with a key and certificate (PEM-format files which you must generate and sign separately), you must edit the unsecured route to add TLS termination.

$ oc edit route/<name>

apiVersion: v1
kind: Route
metadata:
  name: route-name
spec:
  host: www.example.com
  to:
    kind: Service
    name: service-name
  tls:
    termination: edge
    key: |-
      -----BEGIN PRIVATE KEY-----
      [...]
      -----END PRIVATE KEY-----
    certificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    caCertificate: |-
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----

You can specify a secured route without a key and certificate, in which case the router’s default certificate will be used for TLS termination.

Further information on all types of TLS termination as well as path-based routing are available in the Architecture section.

Many OpenShift applications use external resources, such as external databases, or an external SaaS endpoint. These external resources can be modeled as native OpenShift services, so that applications can work with them as they would any other internal service.

One of the most common types of external services is an external database. To support an external database, an application needs:

The solution for integrating with an external database includes:

The following steps outline a scenario for integrating with an external MySQL database:

External Database Environment Variables

Using an external service in your application is similar to using an internal service. Your application will be assigned environment variables for the service and the additional environment variables with the credentials described in the previous step. For example, a MySQL container receives the following environment variables:

The application is responsible for reading the coordinates and credentials for the service from the environment and establishing a connection with the database via the service.

A common type of external service is an external SaaS endpoint. To support an external SaaS provider, an application needs:

The following steps outline a scenario for integrating with an external SaaS provider:

External SaaS Provider Environment Variables

Similarly, when using an internal service, your application is assigned environment variables for the service and the additional environment variables with the credentials described in the above steps. In the above example, the container receives the following environment variables:

The application reads the coordinates and credentials for the service from the environment and establishes a connection with the service.

The Secret object type provides a mechanism to hold sensitive information such as passwords, OpenShift client config files, dockercfg files, etc. Secrets decouple sensitive content from the pods that use it and can be mounted into containers using a volume plug-in or used by the system to perform actions on behalf of a pod. This topic discusses important properties of secrets and provides an overview on how developers can use them.

{
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "namespace": "myns",
  "data": { 1
    "username": "dmFsdWUtMQ0K",
    "password": "dmFsdWUtMg0KDQo="
    }
}

Key properties include:

When creating secrets:

$ oc create -f secret.json

Secret volume sources are validated to ensure that the specified object reference points to a Secret object. Therefore, a secret needs to be created before the pods that depend on it.

Secret API objects reside in a namespace. They can only be referenced by pods in that same namespace.

Individual secrets are limited to 1MB in size. This is to discourage the creation of large secrets that would exhaust apiserver and kubelet memory. However, creation of a number of smaller secrets could also exhaust memory.

Currently, when mounting a secret, the service account for a pod must have the secret in the list of mountable secrets. If a template contains a secret definition and pods that consume it, the pods will be rejected until the service account is updated.

Docker registries can be secured to prevent unauthorized parties from accessing certain images. If you are using OpenShift’s integrated Docker registry and are pulling from image streams located in the same project, then your pod’s service account should already have permissions and no additional action should be required. If this is not the case, then additional configuration steps are required.

OpenShift’s integrated Docker registry authenticates using the same tokens as the OpenShift API. To perform a docker login against the integrated registry, you can choose any user name and email, but the password must be a valid OpenShift token. In order to pull an image, the authenticated user must have get rights on the requested imagestreams/layers. In order to push an image, the authenticated user must have update rights on the requested imagestreams/layers.

By default, all service accounts in a project have rights to pull any image in the same project, and the builder service account has rights to push any image in the same project.

$ oc policy add-role-to-user \
    system:image-puller system:serviceaccount:project-a:default \
    --namespace=project-b

$ oc policy add-role-to-group \
    system:image-puller system:serviceaccounts:project-a \
    --namespace=project-b

To pull a secured Docker image that is not from OpenShift’s integrated registry, you must create a dockercfg secret and add it to your service account.

If you already have a .dockercfg file for the secured registry, you can create a secret from that file by running:

$ oc secrets new <pull_secret_name> \
    .dockercfg=<path/to/.dockercfg>

If you do not already have a .dockercfg file for the secured registry, you can create a secret by running:

$ oc secrets new-dockercfg <pull_secret_name> \
    --docker-server=<registry_server> --docker-username=<user_name> \
    --docker-password=<password> --docker-email=<email>

To use a secret for pulling images for pods, you must add the secret to your service account. The name of the service account in this example should match the name of the service account the pod will use; default is the default service account:

$ oc secrets add serviceaccount/default secrets/<pull_secret_name> --for=pull

To use a secret for pushing and pulling build images, the secret must be mountable inside of a pod. You can do this by running:

$ oc secrets add serviceaccount/builder secrets/<pull_secret_name>

A LimitRange object enumerates the minimum and maximum resource usage values per object in a project.

A LimitRange object can enumerate the following limits for each object type and resource value that is created or modified in the project. If a usage limit is defined, and the incoming resource exceeds the allowed range, then the resource is forbidden from the project.

For some fields, in the absence of a value on the incoming resource, it is possible to apply a default value, if it is specified in the LimitRange definition.

Once a LimitRange is created in a project, all resource create and modification requests are evaluated against each LimitRange object in the project. If the resource violates a minimum or maximum constraint enumerated, then the resource is rejected. If the resource does not set an explicit value, and if the constraint supports a default value, then the default value is applied to the resource.

For example, if the container does not express a CPU resource requirement, but the LimitRange specifies a default value for container CPU, then the default value is set to the allowed CPU usage for that container, and the minimum (if specified) is set as the minimum requested value for that container.

{
  "apiVersion": "v1",
  "kind": "LimitRange",
  "metadata": {
    "name": "limits" 1
  },
  "spec": {
    "limits": [
    {
      "type": "Pod",
      "max": {
        "memory": "1Gi", 2
        "cpu": "2" 3
      },
      "min": {
        "memory": "1Mi", 4
        "cpu": "250m" 5
      }
    },
    {
      "type": "Container",
      "max": {
        "memory": "1Gi", 6
        "cpu": "2" 7
      },
      "min": {
        "memory": "1Mi", 8
        "cpu": "250m" 9
      },
      "default": {
        "memory": "1Mi", 10
        "cpu": "250m" 11
      }
    }
    ]
  }
}

To apply a limit range to a project, create a limit range object definition on your file system to your specifications, then run:

$ oc create -f <limit_range_file>

To view limits enforced in a project:

$ oc get limits
NAME
limits

$ oc describe limits limits
Name:           limits
Type            Resource        Min     Max     Default
----            --------        ---     ---     ---
Pod             memory          1Mi     1Gi     -
Pod             cpu             250m    2       -
Container       memory          1Mi     1Gi     1Mi
Container       cpu             250m    250m    250m

If you do not want to enforce limits in a project, you can remove any active limit range by name:

$ oc delete limits <limit_name>

A ResourceQuota object enumerates hard resource usage limits per project. It limits the total number of a particular type of object that may be created in a project, and the total amount of compute resources that may be consumed by resources in that project.

The following describes the set of limits that may be enforced by a ResourceQuota.

After a project quota is first created, the project restricts the ability to create any new resources that may violate a quota constraint until it has calculated updated usage statistics.

Once a quota is created and usage statistics are up-to-date, the project accepts the creation of new content. When you create or modify resources, your quota usage is incremented immediately upon the request to create or modify the resource. When you delete a resource, your quota use is decremented during the next full recalculation of quota statistics for the project. When you delete resources, a configurable amount of time determines how long it takes to reduce quota usage statistics to their current observed system value.

If project modifications exceed a quota usage limit, the server denies the action, and an appropriate error message is returned to the end-user explaining the quota constraint violated, and what their currently observed usage stats are in the system.

resource-quota.json

{
  "apiVersion": "v1",
  "kind": "ResourceQuota",
  "metadata": {
    "name": "quota" 1
  },
  "spec": {
    "hard": {
      "memory": "1Gi", 2
      "cpu": "20", 3
      "pods": "10", 4
      "services": "5", 5
      "replicationcontrollers":"5", 6
      "resourcequotas":"1" 7
    }
  }
}

To apply a quota to a project:

$ oc create -f resource-quota.json

To view usage statistics related to any hard limits defined in your quota:

$ oc get quota
NAME
quota
$ oc describe quota quota
Name:                   quota
Resource                Used    Hard
--------                ----    ----
cpu                     5       20
memory                  500Mi   1Gi
pods                    5       10
replicationcontrollers  5       5
resourcequotas          1       1
services                3       5

When a set of resources are deleted, the synchronization timeframe of resources is determined by the resource-quota-sync-period setting in the /etc/openshift/master/master-config.yaml file. Before your quota usage is restored, you may encounter problems when attempting to reuse the resources. Change the resource-quota-sync-period setting to have the set of resources regenerate at the desired amount of time (in seconds) and for the resources to be available again:

kubernetesMasterConfig:
  apiLevels:
  - v1beta3
  - v1
  apiServerArguments: null
  controllerArguments:
    resource-quota-sync-period:
      - "10s"

Adjusting the regeneration time can be helpful for creating resources and determining resource usage when automation is used.

Containers are not persistent by default; on restart, their contents are cleared. Volumes are mounted file systems available to pods and their containers which may be backed by a number of host-local or network attached storage endpoints.

The simplest volume type is EmptyDir, which is a temporary directory on a single machine. Administrators may also allow you to request a persistent volume that is automatically attached to your pods.

You can use the CLI command oc volume to add, update, or remove volumes and volume mounts for any object that has a pod template like replication controllers or deployment configurations. You can also list volumes in pods or any object that has a pod template.

The oc volume command uses the following general syntax:

$ oc volume <object_selection> <operation> <mandatory_parameters> <optional_parameters>

This topic uses the form <object_type>/<name> for <object_selection> in later examples, however you can choose one of the following options:

The <operation> can be one of --add, --remove, or --list.

Any <mandatory_parameters> or <optional_parameters> are specific to the selected operation and are discussed in later sections.

To add a volume, a volume mount, or both to pod templates:

$ oc volume <object_type>/<name> --add [options]

Examples

Add a new volume source emptyDir to deployment configuration registry:

$ oc volume dc/registry --add

Add volume v1 with secret $ecret for replication controller r1 and mount inside the containers at /data:

$ oc volume rc/r1 --add --name=v1 --type=secret --secret-name=$ecret --mount-path=/data

Add existing persistent volume v1 with claim name pvc1 to deployment configuration dc.json on disk, mount the volume on container c1 at /data, and update the deployment configuration on the server:

$ oc volume -f dc.json --add --name=v1 --type=persistentVolumeClaim \
  --claim-name=pvc1 --mount-path=/data --containers=c1

Add volume v1 based on Git repository https://github.com/namespace1/project1 with revision 5125c45f9f563 for all replication controllers:

$ oc volume rc --all --add --name=v1 \
  --source='{"gitRepo": {
                "repository": "https://github.com/namespace1/project1",
                "revision": "5125c45f9f563"
            }}'

Updating existing volumes or volume mounts is the same as adding volumes, but with the --overwrite option:

$ oc volume <object_type>/<name> --add --overwrite [options]

Examples

Replace existing volume v1 for replication controller r1 with existing persistent volume claim pvc1:

$ oc volume rc/r1 --add --overwrite --name=v1 --type=persistentVolumeClaim --claim-name=pvc1

Change deployment configuration d1 mount point to /opt for volume v1:

$ oc volume dc/d1 --add --overwrite --name=v1 --mount-path=/opt

To remove a volume or volume mount from pod templates:

$ oc volume <object_type>/<name> --remove [options]

Some examples:

Remove a volume v1 from deployment config 'd1':

$ oc volume dc/d1 --remove --name=v1

Unmount volume v1 from container c1 for deployment configuration d1 and remove the volume v1 if it is not referenced by any containers on d1:

$ oc volume dc/d1 --remove --name=v1 --containers=c1

Remove all volumes for replication controller r1:

$ oc volume rc/r1 --remove --confirm

To list volumes or volume mounts for pods or pod templates:

$ oc volume <object_type>/<name> --list [options]

List volume supported options:

Examples

List all volumes for pod p1:

$ oc volume pod/p1 --list

List volume v1 defined on all deployment configurations:

$ oc volume dc --all --name=v1

A PersistentVolume object is a storage resource in an OpenShift cluster. Storage is provisioned by an administrator by creating PersistentVolume objects from sources such as GCE Persistent Disks, AWS Elastic Block Stores (EBS), and NFS mounts.

Storage can be made available to you by laying claims to the resource. You can make a request for storage resources using a PersistentVolumeClaim object; the claim is paired with a volume that generally matches your request.

You can request storage by creating PersistentVolumeClaim objects in your projects:

{
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
        "name": "claim1"
    },
    "spec": {
        "accessModes": [ "ReadWriteOnce" ],
        "resources": {
            "requests": {
                "storage": "5Gi"
            },
            "volumeName": "pv0001"
        }
    }
}

A PersistentVolume is a specific resource. A PersistentVolumeClaim is a request for a resource with specific attributes, such as storage size. In between the two is a process that matches a claim to an available volume and binds them together. This allows the claim to be used as a volume in a pod. OpenShift finds the volume backing the claim and mounts it into the pod.

You can tell whether a claim or volume is bound by querying using the CLI:

$ oc get pvc
NAME        LABELS    STATUS    VOLUME
claim1      map[]     Bound     pv0001

$ oc get pv
NAME                LABELS              CAPACITY            ACCESSMODES         STATUS    CLAIM
pv0001              map[]               5368709120          RWO                 Bound     yournamespace / claim1

A PersistentVolumeClaim is used by a pod as a volume. OpenShift finds the claim with the given name in the same namespace as the pod, then uses the claim to find the corresponding volume to mount.

{
    "apiVersion": "v1",
    "kind": "Pod",
    "metadata": {
        "name": "mypod",
        "labels": {
            "name": "frontendhttp"
        }
    },
    "spec": {
        "containers": [{
            "name": "myfrontend",
            "image": "nginx",
            "ports": [{
                "containerPort": 80,
                "name": "http-server"
            }],
            "volumeMounts": [{
                "mountPath": "/var/www/html",
                "name": "pvol"
            }]
        }],
        "volumes": [{
            "name": "pvol",
            "persistentVolumeClaim": {
                "claimName": "claim1"
            }
        }]
    }
}

See Kubernetes Persistent Volumes for more information.

You can use the CLI to execute remote commands in a container. This allows you to run general Linux commands for routine operations in the container.

Support for remote container command execution is built into the CLI:

$ oc exec <pod> [-c <container>] <command> [<arg_1> ... <arg_n>]

For example:

$ oc exec mypod date
Thu Apr  9 02:21:53 UTC 2015

Clients initiate the execution of a remote command in a container by issuing a request to the Kubernetes API server:

/proxy/minions/<node_name>/exec/<namespace>/<pod>/<container>?command=<command>

In the above URL:

For example:

/proxy/minions/node123.openshift.com/exec/myns/mypod/mycontainer?command=date

Additionally, the client can add parameters to the request to indicate if:

After sending an exec request to the API server, the client upgrades the connection to one that supports multiplexed streams; the current implementation uses SPDY.

The client creates one stream each for stdin, stdout, and stderr. To distinguish among the streams, the client sets the streamType header on the stream to one of stdin, stdout, or stderr.

The client closes all streams, the upgraded connection, and the underlying connection when it is finished with the remote command execution request.

You can use the CLI to forward one or more local ports to a pod. This allows you to listen on a given or random port locally, and have data forwarded to and from given ports in the pod.

Support for port forwarding is built into the CLI:

$ oc port-forward -p <pod> [<local_port>:]<pod_port> [[<local_port>:]<pod_port> ...]

The CLI listens on each local port specified by the user, forwarding via the protocol described below.

Ports may be specified using the following formats:

For example, to listen on ports 5000 and 6000 locally and forward data to and from ports 5000 and 6000 in the pod, run:

$ oc port-forward -p mypod 5000 6000

To listen on port 8888 locally and forward to 5000 in the pod, run:

$ oc port-forward -p mypod 8888:5000

To listen on a free port locally and forward to 5000 in the pod, run:

$ oc port-forward -p mypod :5000

Or, alternatively:

$ oc port-forward -p mypod 0:5000

Clients initiate port forwarding to a pod by issuing a request to the Kubernetes API server:

/proxy/minions/<node_name>/portForward/<namespace>/<pod>

In the above URL:

For example:

/proxy/minions/node123.openshift.com/portForward/myns/mypod

After sending a port forward request to the API server, the client upgrades the connection to one that supports multiplexed streams; the current implementation uses SPDY.

The client creates a stream with the port header containing the target port in the pod. All data written to the stream is delivered via the Kubelet to the target pod and port. Similarly, all data sent from the pod for that forwarded connection is delivered back to the same stream in the client.

The client closes all streams, the upgraded connection, and the underlying connection when it is finished with the port forwarding request.

There are two types of shared memory objects in Linux: System V and POSIX. The containers in a pod share the IPC namespace of the pod infrastructure container and so are able to share the System V shared memory objects. This document describes how they can also share POSIX shared memory objects.

POSIX shared memory requires that a tmpfs be mounted at /dev/shm. The containers in a pod do not share their mount namespaces so we use volumes to provide the same /dev/shm into each container in a pod. The following example shows how to set up POSIX shared memory between two containers.

---
apiVersion: v1
id: hello-openshift
kind: Pod
metadata:
  name: hello-openshift
  labels:
    name: hello-openshift
spec:
  volumes:                          1
    - name: dshm
      emptyDir:
        medium: Memory
  containers:
    - image: kubernetes/pause
      name: hello-container1
      ports:
        - containerPort: 8080
          hostPort: 6061
      volumeMounts:                 2
        - mountPath: /dev/shm
          name: dshm
    - image: kubernetes/pause
      name: hello-container2
      ports:
        - containerPort: 8081
          hostPort: 6062
      volumeMounts:                 3
        - mountPath: /dev/shm
          name: dshm

Create the pod using the shared-memory.yaml file:

$ oc create -f shared-memory.yaml

In software systems, components can become unhealthy due to transient issues (such as temporary connectivity loss), configuration errors, or problems with external dependencies. OpenShift applications have a number of options to detect and handle unhealthy containers.

A probe is a Kuberbetes action that periodically performs diagnostics on a running container. Currently, two types of probes exist, each serving a different purpose:

Both probes can be configured in three ways:

HTTP Checks

The kubelet uses a web hook to determine the healthiness of the container. The check is deemed successful if the HTTP response code is between 200 and 399. The following is an example of a readiness check using the HTTP checks method:

...
readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 15
  timeoutSeconds: 1
...

A HTTP check is ideal for applications that return HTTP status codes when completely initialized.

Container Execution Checks

The kubelet executes a command inside the container. Exiting the check with status 0 is considered a success. The following is an example of a liveness check using the container execution method:

...
livenessProbe:
  exec:
    command:
    - cat
    - /tmp/health
  initialDelaySeconds: 15
  timeoutSeconds: 1
...

TCP Socket Checks

The kubelet attempts to open a socket to the container. The container is only considered healthy if the check can establish a connection. The following is an example of a liveness check using the TCP socket check method:

...
livenessProbe:
  tcpSocket:
    port: 8080
  initialDelaySeconds: 15
  timeoutSeconds: 1
...

A TCP socket check is ideal for applications that do not start listening until initialization is complete.

For more information on health checks, see the Kubernetes documentation.

OpenShift events are modeled based on events that happen to API objects in an OpenShift cluster. Events allow OpenShift to record information about real-world events in a resource-agnostic manner. They also allow developers and administrators to consume information about system components in a unified way.

This section will be expanded as more information becomes available

This section will be expanded as more information becomes available

OpenShift administrators can consume events directly via an out-of-band interface instead of querying the API server. This can be helpful, for example, if the API server cannot be contacted by a system component in order to record events.

This section will be expanded as more information becomes available

It is common for containers to consume information about API objects. The downward API is a mechanism that allows containers to do this without coupling to OpenShift. Containers can consume information from the downward API using environment variables or a volume plug-in.

Fields within the pod are selected using the FieldRef API type. FieldRef has two fields:

Currently, there are four valid selectors in the v1 API:

The apiVersion field, if not specified, defaults to the API version of the enclosing pod template.

In the future, more information, such as resource limits for pods and information about services, will be available using the downward API.

One mechanism for consuming the downward API is using a container’s environment variables. The EnvVar type’s valueFrom field (of type EnvVarSource) is used to specify that the variable’s value should come from a FieldRef source instead of the literal value specified by the value field. In the future, additional sources may be supported; currently the source’s fieldRef field is used to select a field from the downward API.

Only constant attributes of the pod can be consumed this way, as environment variables cannot be updated once a process is started in a way that allows the process to be notified that the value of a variable has changed. The fields supported using environment variables are:

For example:

Another mechanism for consuming the downward API is using a volume plug-in. The downward API volume plug-in creates a volume with configured fields projected into files. The metadata field of the VolumeSource API object is used to configure this volume. The plug-in supports the following fields:

spec:
  volumes:
    - name: podinfo
      metadata: 1
        items:  2
          - name: "labels" 3
            fieldRef:
              fieldPath: metadata.labels 4

For example:

You can set, unset or list environment variables in pods or pod templates using the oc env command.

OpenShift provides the oc env command to set or unset environment variables for objects that have a pod template, such as replication controllers or deployment configurations. It can also list environment variables in pods or any object that has a pod template.

The oc env command uses the following general syntax:

$ oc env <object-selection> <environment-variables> [options]

There are several ways to express <object-selection>.

Supported common options for set, unset or list environment variables:

To set environment variables in the pod templates:

$ oc env <object-selection> KEY_1=VAL_1 ... KEY_N=VAL_N [<set-env-options>] [<common-options>]

Set environment options:

In the following example, both commands modify environment variable STORAGE in the deployment config registry. The first adds, with value /data. The second updates, with value /opt.

$ oc env dc/registry STORAGE=/data
$ oc env dc/registry --overwrite STORAGE=/opt

The following example finds environment variables in the current shell whose names begin with RAILS_ and adds them to the replication controller r1 on the server:

$ env | grep RAILS_ | oc env rc/r1 -e -

The following example does not modify the replication controller defined in file rc.json. Instead, it writes a YAML object with updated environment STORAGE=/local to new file rc.yaml.

$ oc env -f rc.json STORAGE=/opt -o yaml > rc.yaml

To unset environment variables in the pod templates:

$ oc env <object-selection> KEY_1- ... KEY_N- [<common-options>]

This example removes environment variables ENV1 and ENV2 from deployment config d1:

$ oc env dc/d1 ENV1- ENV2-

This removes environment variable ENV from all replication controllers:

$ oc env rc --all ENV-

This removes environment variable ENV from container c1 for replication controller r1:

$ oc env rc r1 --containers='c1' ENV-

To list environment variables in pods or pod templates:

$ oc env <object-selection> --list [<common-options>]

This example lists all environment variables for pod p1:

$ oc env pod/p1 --list

OpenShift Enterprise 3.0 release.