Chapter 4. Project Management

Listing all the pods in an environment requires one request:

The GET request returns the PodList, listing the details of all pods in the environment.

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/pods

Listing all the pods in a namespace requires one request:

The GET request returns the PodList, listing the details of all pods in the namespace.

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/pods

Listing a specific pod configuration requires one request:

The GET request returns the Pod configuration for the specified pod.

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/pods/{$POD}

Idling consists of a series of requests:

Idling an endpoint requires a PATCH request to the endpoint, and a PUT request to the referenced owner of the resources. GET requests 1-3 discover the pods corresponding to the endpoint, the owner resource of the pods, and then discover if that owner resource is owned by another resource.

GET request 4 is optional as the replica value for the resource is in the configuration returned in a previous GET request; however, returning the scale subresource can simplify the process of retrieving the replica value.

The PATCH request adds annotations to the endpoint that include the time in which the resource is considered idle, and an owner reference so that the owner resource is scaled accordingly when a service receives traffic. The PUT request to the owner resource includes the same idle time annotation as the endpoint, the previous replica value of the resource to scale to when unidled, and replaces the replica value to 0 to idle the resource.

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml \
-H "Content-Type: application/yaml" \
https://{$OPENSHIFT_ENVIRONMENT_URL}:8443/api/v1/namespaces/{$PROJECT}/endpoints/{$ENDPOINT}

Response Body Snippet

...
subsets:
- addresses:
  - ip: 192.0.2.1
    nodeName: {$OPENSHIFT_NODE_URL}
    targetRef:
      kind: Pod
      name: {$POD1}
      namespace: {$PROJECT}
      resourceVersion: "213472"
      uid: 6acc03a4-41cd-11e7-a37b-1418776f4b43
  - ip: 192.0.2.2
    nodeName: {$OPENSHIFT_NODE_URL}
    targetRef:
      kind: Pod
      name: {$POD2}
      namespace: {$PROJECT}
      resourceVersion: "213472"
      uid: 6acc02e0-41cd-11e7-a37b-1418776f4b43
...

The request returns two pods corresponding to the endpoint.

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml \
-H "Content-Type: application/yaml" \
https://{$OPENSHIFT_ENVIRONMENT_URL}:8443/api/v1/namespaces/{$PROJECT}/pods/{$POD1}

Response Body Snippet

...
kind: Pod
metadata:
  annotations:
    kubernetes.io/created-by: |
      {"kind":"SerializedReference","apiVersion":"v1","reference":{"kind":"ReplicationController","namespace":"{$PROJECT}","name":"{$REPLICATIONCONTROLLER}","uid":"e45f3d69-3b9a-11e7-a37b-1418776f4b43","apiVersion":"v1","resourceVersion":"213449"}}
    openshift.io/deployment-config.latest-version: "1"
    openshift.io/deployment-config.name: {$DEPLOYMENTCONFIG}
    openshift.io/deployment.name: {$DEPLOYMENT}
    openshift.io/scc: restricted
...

The pod owner is discovered from the kubernetes.io/created-by: and the openshift.io/deployment-config.name: annotations. The pod in this example has two owners: {$REPLICATIONCONTROLLER} and {$DEPLOYMENTCONFIG}.

For the purposes of the example, {$POD2} has the same owners.

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
https://{$OPENSHIFT_ENVIRONMENT_URL}:8443/api/v1/namespaces/{$PROJECT}/replicationcontrollers/{$REPLICATIONCONTROLLER}

Response Body Snippet

...
kind: ReplicationController
metadata:
  annotations:
    openshift.io/deployer-pod.name: {$DEPLOYER_POD}
    openshift.io/deployment-config.latest-version: "1"
    openshift.io/deployment-config.name: {$DEPLOYMENTCONFIG}
...

The replication owner is discovered with the openshift.io/deployment-config.name: annotation. The replication controller in this example is also owned by {$DEPLOYMENTCONFIG}.

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
https://{$OPENSHIFT_ENVIRONMENT_URL}:8443/oapi/v1/namespaces/{$PROJECT}/deploymentconfigs/{$DEPLOYMENTCONFIG}

Response Body Snippet

...
kind: DeploymentConfig
metadata:
  annotations:
    openshift.io/generated-by: OpenShiftWebConsole
...

The returned deploymentconfig shows no owner, confirming that {$DEPLOYMENTCONFIG} is the sole owner of {$POD1} and {$POD2}.

Request Header

curl -k -v \
-X PUT \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
https://{$OPENSHIFT_ENVIRONMENT_URL}:8443/oapi/v1/namespaces/{$PROJECT}/deploymentconfigs/{$DEPLOYMENTCONFIG}/scale

Response Body Snippet

...
kind: Scale
spec:
  replicas: 2
...

The deploymentconfig has a replica value of 2. This will be used when updating the deploymentconfig to idle the resources.

Request Header

curl -k -v \
-X PATCH \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/json" \
-H "Content-Type: text/strategic-merge-patch+json" \
https://{$OPENSHIFT_ENVIRONMENT_URL}:8443/api/v1/namespaces/{$PROJECT}/endpoints/{$ENDPOINT}

Request Body

{
  "metadata":
    "annotations": {
      "idling.alpha.openshift.io/idled-at": "2017-06-21T04:18:54Z",
      "idling.alpha.openshift.io/unidle-targets": "[{\"kind\":\"DeploymentConfig\",\"name\":\"{$DEPLOYMENTCONFIG}\",\"replicas\":2}]"
    }
}

The idling.alpha.openshift.io/idled-at: annotation indicates the time at which the endpoint is considered idled. The same annotation is used for the owner in the next step.
The idling.alpha.openshift.io/unidle-targets: annotation indicates that the endpoint will unidle the owner.

Request Header

curl -k -v \
-X PUT \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
https://{$OPENSHIFT_ENVIRONMENT_URL}:8443/oapi/v1/namespaces/{$PROJECT}/deploymentconfigs/{$DEPLOYMENTCONFIG}

Request Body Snippet

...
kind: DeploymentConfig
metadata:
  annotations:
    idling.alpha.openshift.io/idled-at: 2017-06-21T04:18:54Z
    idling.alpha.openshift.io/previous-scale: "2"
    openshift.io/generated-by: OpenShiftWebConsole
...
spec:
  replicas: 0
...

The PUT request uses the deploymentconfig returned in a previous request, modified with the following:

Deployment rollback consists of two requests:

The POST request body specifies which elements of the deployment configuration version spec to be included in the returned deploymentconfig. The request returns a new deploymentconfig that represents the rollback state and can be used verbatim in the request body of the PUT request.

The PUT request body sends the returned deploymentconfig configuration to the deployment name in the subresource. This triggers a new deployment that effectively rolls back the deployment to the version specified in the returned deploymentconfig.

Request Header

curl -k -v \
-X POST  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/deploymentconfigs/{$DEPLOYMENT}/rollback

Request Body

apiVersion: v1
kind: DeploymentConfigRollback
name: {$DEPLOYMENT}
spec:
  from:
    name: {$DEPLOYMENT}-{$VERSION}
  includeTriggers: false
  includeTemplate: true
  includeReplicationMeta: false
  includeStrategy: false

Request Header

curl -k -v \
-X PUT \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/deploymentconfigs/{$DEPLOYMENT}

Request Body

Use the response body returned by the POST request as the request body. No changes are necessary.

Scaling a deployment consists of two requests:

The GET request returns the Scale configuration.
The GET request is optional if an updated Scale configuration can otherwise be provided for the PUT request.

Update the spec: replicas parameter in the Scale configuration. Send the configuration as the request body in a PUT request to the scale subresource of the deployment.

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/deploymentconfigs/{$DEPLOYMENT}/scale

Request Header

curl -k -v
curl -k -v \
-X PUT \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/deploymentconfigs/{$DEPLOYMENT}/scale

Request Body Snippet

...
spec:
  replicas: 3
...

Scaling a replication controller consists of two requests:

The GET request returns the ReplicationController configuration.
The GET request is optional if an updated ReplicationController configuration can otherwise be provided for the PUT request. The ReplicationController configuration includes an encoded deploymentconfig for the deployment being scaled.

Update the spec: replicas parameter in the ReplicationController configuration. Send the configuration as the request body in a PUT request to the deployment replicationcontrollers resource.

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
GET {$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/replicationcontrollers/{$DEPLOYMENT}-{$VERSION}

Request Header

curl -k -v \
-X PUT \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/api/v1/namespaces/{$PROJECT}/replicationcontrollers/{$DEPLOYMENT}-{$VERSION}

Request Body Snippet

...
spec:
  replicas: 3
...

Scaling a job consists of two requests:

The GET request returns a Job configuration.
The GET request is optional if an updated Job configuration can otherwise be provided for the PUT request.

Update the spec: parallelism parameter in the Job configuration. Send the configuration as the request body in a PUT request to the deployment jobs subresource.

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/apis/batch/v1/namespaces/{$PROJECT}/jobs/{$JOB}

Request Header

curl -k -v \
-X PUT \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/apis/batch/v1/namespaces/{$PROJECT}/jobs/{$JOB}

Request Body Snippet

...
spec:
  parallelism: 3
...

Creating a new route requires one request:

The POST request uses a Route configuration in the request body.
The following request example uses the minimum required fields to expose a service with an insecure route.

Request Header

curl -k -v \
-X POST \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/routes

Request Body

apiVersion: v1
kind: Route
metadata:
  name: {$ROUTE_NAME}
spec:
  to:
    kind: Service
    name: {$SERVICE_NAME}

Listing the configurations for all routes in an environment requires one request:

The GET request returns the RouteList, listing the details of all routes in the environment.

Request Header

curl -k -v \
-X GET \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/routes

Listing the configurations for all services in a namespace requires one request:

The GET request returns the RouteList, listing the details of all routes in the namespace.

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/routes

Listing a specific Route configuration requires one request:

The GET request returns the Route configuration for the specified route.

Request Header

curl -k -v \
-X GET  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/routes/{$ROUTE}

The following PATCH request example adds an alternate service to the route and updates the original service with an equal weight:

Request Header

curl -k -v \
-X PATCH \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/json" \
-H "Content-Type: text/strategic-merge-patch+json" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/
routes/{$ROUTE}

Request Body

{
  "spec": {
     "to": {
      "weight": 1
     },
     "alternateBackends": [
       {
        "kind": "Service",
        "name": "{$ALT_SERVICE}",
        "weight": 1
       }
    ]
  }
}

Deleting a route requires one request:

The DELETE request returns a code: 200 and the route is deleted.

Request Header

curl -k -v \
-X DELETE  \
-H "Authorization: {$BEARER_TOKEN}" \
-H "Accept: application/yaml" \
-H "Content-Type: application/yaml" \
{$OCP_CLUSTER}/oapi/v1/namespaces/{$PROJECT}/routes/{$ROUTE}