Kubernetes API Fundamentals

Difficulty: beginner

Estimated Time: 30 minutes

Before diving into the Operator Framework, this section will give an overview of Kubernetes API fundamentals. Although the Operator SDK makes creating an Operator fun and easy, understanding the structure and features of the Kubernetes API is required.

For more information, check out the links below:

Git Hub

Operator-Framework: https://github.com/operator-framework
Operator-SDK: https://github.com/operator-framework/operator-sdk/

Chat

Kubernetes Slack Chat (upstream): #kubernetes-operators at https://kubernetes.slack.com/
Operator-Framework on Google Groups: https://groups.google.com/forum/#!forum/operator-framework
OpenShift Operators Special Interest Group (SIG): https://commons.openshift.org/sig/OpenshiftOperators.html

Your environment is currently being packaged as a Docker container and the download will begin shortly. To run the image locally, once Docker has been installed, use the commands

cat scrapbook_openshift_operatorframework/k8s-api-fundamentals_container.tar | docker load

docker run -it /openshift_operatorframework/k8s-api-fundamentals:

Restart Scenario

Next Scenario

Step 1 of 5

Kubernetes Manifests

Let's begin by creating a new project called myproject:

oc new-project myproject

Create a new pod manifest that specifies two containers:

cat > pod-multi-container.yaml <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: my-two-container-pod
  namespace: myproject
  labels:
    environment: dev
spec:
  containers:
    - name: server
      image: nginx:1.13-alpine
      ports:
        - containerPort: 80
          protocol: TCP
    - name: side-car
      image: alpine:latest
      command: ["/usr/bin/tail", "-f", "/dev/null"]
  restartPolicy: Never
EOF

Create the pod by specifying the manifest:

oc create -f pod-multi-container.yaml

View the detail for the pod and look at the events:

oc describe pod my-two-container-pod

Let's first execute a shell session inside the server container by using the -c flag:

oc exec -it my-two-container-pod -c server -- /bin/sh

Run some commands inside the server container:

ip address
netstat -ntlp
hostname
ps
exit

Let's now execute a shell session inside the side-car container:

oc exec -it my-two-container-pod -c side-car -- /bin/sh

Run the same commands in side-car container. Each container within a pod runs it's own cgroup, but shares IPC, Network, and UTC (hostname) namespaces:

ip address
netstat -ntlp
hostname
exit

Basic Operations with the Kubernetes API

Verify the currently available Kubernetes API versions:

oc api-versions

Use the --v flag to set a verbosity level. This will allow you to see the request/responses against the Kubernetes API:

oc get pods --v=8

Use the oc proxy command to proxy local requests on port 8001 to the Kubernetes API:

oc proxy --port=8001

Open up another terminal by clicking the + button and select Open New Terminal.

Send a GET request to the Kubernetes API using curl:

curl -X GET http://localhost:8001

We can explore the OpenAPI definition file to see complete API details.

curl localhost:8001/openapi/v2

Send a GET request to list all pods in the environment:

curl -X GET http://localhost:8001/api/v1/pods

Use jq to parse the json response:

curl -X GET http://localhost:8001/api/v1/pods | jq .items[].metadata.name

We can scope the response by only viewing all pods in a particular namespace:

curl -X GET http://localhost:8001/api/v1/namespaces/myproject/pods

Get more details on a particular pod within the myproject namespace:

curl -X GET http://localhost:8001/api/v1/namespaces/myproject/pods/my-two-container-pod

Export the manifest associated with my-two-container-pod in json format:

oc get pods my-two-container-pod --export -o json > podmanifest.json

Within the manifest, replace the 1.13 version of alpine with 1.14:

sed -i 's|nginx:1.13-alpine|nginx:1.14-alpine|g' podmanifest.json

Update/Replace the current pod manifest with the newly updated manifest:

curl -X PUT http://localhost:8001/api/v1/namespaces/myproject/pods/my-two-container-pod -H "Content-type: application/json" -d @podmanifest.json

Patch the current pod with a newer container image (1.15):

curl -X PATCH http://localhost:8001/api/v1/namespaces/myproject/pods/my-two-container-pod -H "Content-type: application/strategic-merge-patch+json" -d '{"spec":{"containers":[{"name": "server","image":"nginx:1.15-alpine"}]}}'

Delete the current pod by sending the DELETE request method:

curl -X DELETE http://localhost:8001/api/v1/namespaces/myproject/pods/my-two-container-pod

Verify the pod is in Terminating status:

oc get pods

Verify the pod no longer exists:

curl -X GET http://localhost:8001/api/v1/namespaces/myproject/pods/my-two-container-pod

Replica Sets

Get a list of all pods in the myproject Namespace:

oc get pods -n myproject

Create a ReplicaSet object manifest file:

cat > replica-set.yaml <<EOF
apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: myfirstreplicaset
  namespace: myproject
spec:
  selector:
    matchLabels:
     app: myfirstapp
  replicas: 3
  template:
    metadata:
      labels:
        app: myfirstapp
    spec:
      containers:
        - name: nodejs
          image: openshiftkatacoda/blog-django-py
EOF

Create the ReplicaSet:

oc apply -f replica-set.yaml

In a new terminal window, select all pods that match app=myfirstapp:

oc get pods -l app=myfirstapp --show-labels -w

Delete the pods and watch new ones spawn:

oc delete pod -l app=myfirstapp

Imperatively scale the ReplicaSet to 6 replicas:

oc scale replicaset myfirstreplicaset --replicas=6

Imperatively scale down the ReplicaSet to 3 replicas:

oc scale replicaset myfirstreplicaset --replicas=3

The oc scale command interacts with the /scale endpoint:

curl -X GET http://localhost:8001/apis/apps/v1/namespaces/myproject/replicasets/myfirstreplicaset/scale

Use the PUT method against the /scale endpoint to change the number of replicas to 5:

curl  -X PUT localhost:8001/apis/apps/v1/namespaces/myproject/replicasets/myfirstreplicaset/scale -H "Content-type: application/json" -d '{"kind":"Scale","apiVersion":"autoscaling/v1","metadata":{"name":"myfirstreplicaset","namespace":"myproject"},"spec":{"replicas":5}}'

You can also get information regarding the pod by using the GET method against the /status endpoint

curl -X GET http://localhost:8001/apis/apps/v1/namespaces/myproject/replicasets/myfirstreplicaset/status

The status endpoint's primary purpose is to allow a controller (with proper RBAC permissions) to send a PUT method along with the desired status.

Deployments/Finalizers

Create a manifest for a Deployment with a Finalizer:

cat > finalizer-test.yaml<<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: finalizer-test
  namespace: myproject
  labels:
    app: finalizer-test
  finalizers:
    - finalizer.extensions/v1beta1  
spec:
  selector:
    matchLabels:
      app: finalizer-test
  replicas: 3
  template:
    metadata:
      labels:
        app: finalizer-test
    spec:
      containers:
        - name: hieveryone
          image: openshiftkatacoda/blog-django-py
          imagePullPolicy: Always
          ports:
            - name: helloworldport
              containerPort: 8080
EOF

Create the Deployment.

oc create -f finalizer-test.yaml

Verify the Deployment has been created.

oc get deploy

Verify the ReplicaSet has been created:

oc get replicaset

Verify the pods are running:

oc get pods

Attempt to delete the Deployment.

oc delete deployment finalizer-test

Open up another terminal by clicking the + button and select Open New Terminal.

Observe the Deployment still exits and has been updated with the deletionGracePeriodSeconds and deletionTimestamp fields.

oc get deployment finalizer-test -o yaml | grep 'deletionGracePeriodSeconds\|deletionTimestamp'

Attempt to scale the Deployment up and down. Although status is updated, pods will not be created/deleted:

oc scale deploy finalizer-test --replicas=5
oc scale deploy finalizer-test --replicas=1

oc get deploy
oc get pods

Update the Deployment with the Finalizer value unset.

cat > finalizer-test-remove.yaml<<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: finalizer-test
  namespace: myproject
  labels:
    app: finalizer-test
  finalizers:
spec:
  selector:
    matchLabels:
      app: finalizer-test
  replicas: 3
  template:
    metadata:
      labels:
        app: finalizer-test
    spec:
      containers:
        - name: hieveryone
          image: openshiftkatacoda/blog-django-py
          imagePullPolicy: Always
          ports:
            - name: helloworldport
              containerPort: 8080
EOF

Replace the Deployment.

oc replace -f finalizer-test-remove.yaml

The Deployment will now be deleted.

oc get deploy
oc get pods

See the following:

Deployment Controller (DeletionTimestamp != nil)

SyncStatusOnly Method

Custom Resource Definitions

Begin by running a proxy to the Kubernetes API server:

oc proxy --port=8001

Open up another terminal by clicking the + button and select Open New Terminal.

Let's create a new Custom Resource Definition (CRD) object manifest for Postgres:

cat >> postgres-crd.yaml <<EOF
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: postgreses.rd.example.com
spec:
  group: rd.example.com
  names:
    kind: Postgres
    listKind: PostgresList
    plural: postgreses
    singular: postgres
    shortNames:
    - pg
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        type: object
        x-kubernetes-preserve-unknown-fields: true
    served: true
    storage: true
EOF

Create the CRD resource object:

oc create -f postgres-crd.yaml

You should now see the Kubernetes API reflect a brand new api group called rd.example.com:

curl http://localhost:8001/apis | jq .groups[].name

This will also be reflected in the oc api-versions command:

oc api-versions

Within the rd.example.com group there will be an api version v1alpha1 (per our CRD resource object). The database resource resides here.

curl http://localhost:8001/apis/rd.example.com/v1alpha1 | jq

Notice how oc now recognize postgres as a present resource (although there will be no current resource objects at this time).

oc get postgres

Let's create a new Custom Resource (CR) object manifest for the database:

cat >> wordpress-database.yaml <<EOF
apiVersion: "rd.example.com/v1alpha1"
kind: Postgres
metadata:
  name: wordpressdb
spec:
  user: postgres
  password: postgres
  database: primarydb
  nodes: 3
EOF

Create the new object:

oc create -f wordpress-database.yaml

Verify the resource was created:

oc get postgres

View the details about the wordpressdb object:

oc get postgres wordpressdb -o yaml

Terminal

Console

cd <directory>	Change directory
ls	List directory
echo 'contents' > <file>	Write contents to a file
cat <file>	Output contents of file

i	In Command Mode	Change into Insert Mode, you can now insert and edit text in the file
esc	In Insert Mode	Change into Command Mode, you can now execute commands
:wq	In Command Mode	Save and Exit

Welcome!

Kubernetes API Fundamentals

Congratulations!

You've completed the scenario!

Scenario Rating

Git Hub

Chat

Steps