Pull an Image from Oracle Cloud Infrastructure Registry when Deploying a Load-Balanced Application to a Cluster

Before You Begin

This 15-minute tutorial shows you how to:

create a named secret containing Oracle Cloud Infrastructure credentials
add the named secret to a manifest .yml file, along with the name and location of an image to pull from Oracle Cloud Infrastructure Registry
use the manifest .yml file to deploy the helloworld application to a Kubernetes cluster and create an Oracle Cloud Infrastructure load balancer
verify that the helloworld application is working as expected, and that the load balancer is distributing requests between the nodes in a cluster

Background

Oracle Cloud Infrastructure Registry is an Oracle-managed registry that enables you to simplify your development to production workflow. Oracle Cloud Infrastructure Registry makes it easy for you as a developer to store, share, and manage development artifacts like Docker images. And the highly available and scalable architecture of Oracle Cloud Infrastructure ensures you can reliably deploy your applications. So you don't have to worry about operational issues, or scaling the underlying infrastructure.

Oracle Cloud Infrastructure Container Engine for Kubernetes is a fully-managed, scalable, and highly available service that you can use to deploy your containerized applications to the cloud. Use Container Engine for Kubernetes when your development team wants to reliably build, deploy, and manage cloud-native applications. You specify the compute resources that your applications require, and Container Engine for Kubernetes provisions them on Oracle Cloud Infrastructure in an existing OCI tenancy.

This tutorial assumes you have already completed:

the Pushing an Image to Oracle Cloud Infrastructure Registry tutorial
the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial

What Do You Need?

You must have met the prerequisites for the Pushing an Image to Oracle Cloud Infrastructure Registry tutorial, and successfully completed the tutorial. Redo the Pushing an Image to Oracle Cloud Infrastructure Registry tutorial if you did not successfully:

Create an auth token. You'll need the value of that auth token to complete this tutorial. If you don't have the auth token value, go back to the Pushing an Image to Oracle Cloud Infrastructure Registry tutorial and follow the instructions to create a new auth token.
Push the helloworld image to a private repository in Oracle Cloud Infrastructure Registry. By default, the image you pushed would have been pushed to a private repository, which can only be accessed by supplying an auth token.

You must have met the prerequisites for the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial, and successfully completed the tutorial. Redo the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial if you did not successfully:

Create a suitably configured VCN and related resources (if they didn't exist already).
Create a new Kubernetes cluster, and add a node pool to the new cluster.
Set up the Kubernetes configuration file for the cluster (the cluster's 'kubeconfig' file) as a file named config located in the $HOME/.kube/config directory. The kubeconfig file enables you to access the cluster using kubectl and the Kubernetes Dashboard. Note that if you didn't store the kubeconfig file as $HOME/.kube/config, you'll have to explicitly set the KUBECONFIG environment variable to point to the kubeconfig file whenever you use kubectl in a new terminal window.

You must have sufficient Oracle Cloud Infrastructure Load Balancing service quota available in your region to create a 100Mbps load balancer.

Getting Ready for the Tutorial

Confirm that you have the value for the Tutorial auth token that you created in the Pushing an Image to Oracle Cloud Infrastructure Registry tutorial. If you don't have the auth token value, go back to that tutorial and follow the instructions to create a new auth token.
Verify that you can use kubectl to connect to the cluster you created in the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial by entering the following command in a terminal window:
```
$ kubectl get nodes
```
You see details of the nodes running in the cluster. For example:
```
NAME               STATUS   ROLES   AGE   VERSION
10.0.10.2          Ready    node    1d    v1.18.10
10.0.11.2          Ready    node    1d    v1.18.10
10.0.12.2          Ready    node    1d    v1.18.10
```
You've confirmed that the cluster is up and running as expected. You can now deploy an application to the cluster.

Create a Secret for the Tutorial

To enable Kubernetes to pull an image from Oracle Cloud Infrastructure Registry when deploying an application, you need to create a Kubernetes secret. The secret includes all the login details you would provide if you were manually logging in to Oracle Cloud Infrastructure Registry using the docker login command, including your auth token.

In a terminal window, enter the following command:
```
$ kubectl create secret docker-registry ocirsecret
--docker-server=<region-key>.ocir.io --docker-username='<tenancy-namespace>/<oci-username>' --docker-password='<oci-auth-token>' --docker-email='<email-address>'
```
where:
- ocirsecret is the name of the secret you're creating, and that you'll use in the manifest file to refer to the secret. For the purposes of this tutorial, you must name the secret ocirsecret. When you've completed the tutorial and are creating your own secrets for your own use, you can choose what to call your secrets.
- <region-key> is the key for the Oracle Cloud Infrastructure Registry region you're using. For example, phx. See the Availability by Region topic in the Oracle Cloud Infrastructure Registry documentation.
- ocir.io is the Oracle Cloud Infrastructure Registry name.
- <tenancy-namespace> is the auto-generated Object Storage namespace string of the tenancy (as shown on the Tenancy Information page) containing the repository from which the application is to pull the image. For example, the namespace of the acme-dev tenancy might be ansh81vru1zp.
- <oci-username> is the username to use when pulling the image. The username must have access to the tenancy specified by tenancy-namespace. For example, jdoe@acme.com. If your tenancy is federated with Oracle Identity Cloud Service, use the format /oracleidentitycloudservice/<oci-username>.
- <oci-auth-token> is the auth token of the user specified by oci-username. For example, k]j64r{1sJSSF-;)K8
- <email-address> is an email address. An email address is required, but it doesn't matter what you specify. For example, jdoe@acme.com
Note the use of single quotes around strings containing special characters.

For example, combining the previous examples, you might enter:
```
$ kubectl create secret docker-registry ocirsecret --docker-server=phx.ocir.io --docker-username='ansh81vru1zp/jdoe@acme.com' --docker-password='k]j64r{1sJSSF-;)K8'
--docker-email='jdoe@acme.com'
```
Verify that the secret has been created by entering:
```
$ kubectl get secrets
```
Details about the ocirsecret secret you just created are shown.

Having created the secret, you can now refer to it in the application's manifest file.

Add the Secret and the Image Path to the Manifest File

Having created the secret, you now include the name of the secret in the manifest file that Kubernetes uses when deploying the helloworld application to a cluster. You also include in the manifest file the path to the helloworld image in Oracle Cloud Infrastructure Registry.

Create a new text file with the name helloworld-lb.yml in a local directory accessible to kubectl.
Open the new helloworld-lb.yml file in a text editor.
Copy and paste the following text into the helloworld-lb.yml file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: helloworld-deployment
spec:
  selector:
    matchLabels:
      app: helloworld
  replicas: 1
  template:
    metadata:
      labels:
        app: helloworld
    spec:
      containers:
      - name: helloworld
    # enter the path to your image, be sure to include the correct region prefix    
        image: <region-key>.ocir.io/<tenancy-namespace>/<repo-name>:<tag>
        ports:
        - containerPort: 80
      imagePullSecrets:
    # enter the name of the secret you created  
      - name: <secret-name>
---
apiVersion: v1
kind: Service
metadata:
  name: helloworld-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: helloworld

Change the following line in the helloworld-lb.yml file to include the path you specified when you pushed the helloworld image to Oracle Cloud Infrastructure Registry in the Pushing an Image to Oracle Cloud Infrastructure Registry tutorial:
```
image: <region-key>.ocir.io/<tenancy-namespace>/<repo-name>:<tag>
```
For example, if you gave the image the tag phx.ocir.io/ansh81vru1zp/helloworld:latest, then change the line to read:
```
image: phx.ocir.io/ansh81vru1zp/helloworld:latest
```
Change the following line in the helloworld-lb.yml file to include the name of the secret you created earlier:
```
name: <secret-name>
```
As you gave the secret the name ocirsecret, change the line to read:
```
name: ocirsecret
```
Save the helloworld-lb.yml file in a local directory accessible to kubectl, and close the file.

Deploy the helloworld Application

Having updated the helloworld application's manifest file, you can now deploy the application.

In a terminal window, deploy the sample helloworld application to the cluster by entering:
```
$ kubectl create -f <local-path>/helloworld-lb.yml
```
where <local-path> is the location of the helloworld-lb.yml file.
Messages confirm that the deployment helloworld-deployment and the service helloworld-service load balancer have both been created.

The helloworld-service load balancer is implemented as an Oracle Cloud Infrastructure load balancer with a backend set to route incoming traffic to nodes in the cluster. You can see the new load balancer on the Load Balancers page in the Oracle Cloud Infrastructure Console.

Verify the Load-balanced helloworld Application Is Working Correctly

In a terminal window, enter the following command:
```
$ kubectl get services
```
You see details of the services running on the nodes in the cluster. For the helloworld-service load balancer that you just deployed, you see:

the external IP address of the load balancer (for example, 129.146.147.91)
the port number

Open a new browser window and enter the url to access the helloworld application in the browser's URL field. For example, http://129.146.147.91

When the load balancer receives the request to access the helloworld application, the load balancer routes the request to one of the available nodes in the cluster. The results of the request are returned to the browser, which displays a page with a message like:

Hello

Is it me you're looking for?

Browser window — Description of the illustration

At the bottom of the page, a page view counter shows the number of times the page has been visited, and initially displays '1'.

Reload the page in the browser window (for example, by clicking Refresh or Reload).

Description of the illustration

The counter at the bottom of the page now displays '2'.

Congratulations! You've successfully deployed the helloworld application. Kubernetes used the secret you created to pull the helloworld image from Oracle Cloud Infrastructure Registry. It then deployed the image and created an Oracle Cloud Infrastructure load balancer to distribute requests between the nodes in the cluster. Finally, you've verified that the application is working as expected.

Housekeeping

Having completed the tutorial, you can now delete the application you deployed on the cluster. If you want to free up Oracle Cloud Infrastructure resources, you can also delete the VCN and the cluster that you created in the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial. On the other hand, because it took a while to set up the VCN and the cluster, it's a good idea to retain them (especially the VCN) for your own testing purposes.

In a terminal window, enter the following command to delete the helloworld application:
```
$ kubectl delete deployment helloworld-deployment
```
When you delete the deployment, any running pods are automatically deleted as well.
Enter the following command to delete the load balancer service:
```
$ kubectl delete service helloworld-service
```
When you delete the load balancer service, the Oracle Cloud Infrastructure load balancer is automatically deleted as well.

Optionally, you can free up Oracle Cloud Infrastructure resources by deleting the cluster and the VCN that you created in the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial.
(optional) To delete the cluster you created in the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial (named Tutorial Cluster in that tutorial):

In the Console, open the navigation menu. Under Solutions and Platform, go to Developer Services and click Kubernetes Clusters.
Click the name of the cluster you created for the tutorial.
Click Delete Cluster.

Description of the illustration
Confirm that you want to delete the cluster.

(optional) To delete the VCN you created in the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes tutorial (named oke-vcn-quick-Tutorial Cluster-<creation_date> in that tutorial):
1. In the Console, open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
2. Click the name of the VCN you created, and then click Terminate on the Details page.
3. Confirm that you want to terminate the VCN.

Want to Learn More?

Overview of Registry