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

section 0Before 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:

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 and Deploying a Sample App tutorial, and successfully completed the tutorial. Redo the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes and Deploying a Sample App 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.
    • Download 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.
    • Deploy a sample helloworld app to the cluster.
  • You must have sufficient Oracle Cloud Infrastructure Load Balancing service quota available in your region to create a 100Mbps load balancer.

section 1Getting Ready for the Tutorial

  1. 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.
  2. 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 and Deploying a Sample App 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
    129.146.102.157    Ready    node    1d    v1.8.11
    129.146.110.67     Ready    node    1d    v1.8.11
    129.146.136.139    Ready    node    1d    v1.8.11
    

    You've confirmed that the cluster is up and running as expected. You can now deploy an application to the cluster.


section 2Create 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.

  1. In a terminal window, enter the following command:
    $ kubectl create secret docker-registry ocirsecret
    --docker-server=<region-code>.ocir.io --docker-username='<tenancy-name>/<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-code> is one of fra, iad, lhr, or phx
    • ocir.io is the Oracle Cloud Infrastructure Registry name.
    • <tenancy-name> is the tenancy containing the repository from which the application is to pull the image. For example, acme-dev
    • <oci-username> is the username to use when pulling the image. The username must have access to the tenancy specified by tenancy-name. 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='acme-dev/jdoe@acme.com' --docker-password='k]j64r{1sJSSF-;)K8'
    --docker-email='jdoe@acme.com'
  2. Verify that the secret has been created by entering:
    $ kubectl get secrets
    Details about the ocirsecret secret you just created are shown.
  3. Having created the secret, you can now refer to it in the application's manifest file.


section 3Add 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.

  1. Open a new file in a text editor.
  2. Copy and paste the following text into the new file:
  3. 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-code>.ocir.io/<tenancy-name>/<repo-name>/<image-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
  4. Change the following line in the 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-code>.ocir.io/<tenancy-name>/<repo-name>/<image-name>:<tag>
    For example, if you gave the image the tag phx.ocir.io/acme-dev/helloworld:latest, then change the line to read:
    image: phx.ocir.io/acme-dev/helloworld:latest
  5. Change the following line in the 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
  6. Save the file with the name helloworld-lb.yml in a local directory accessible to kubectl, and close the file.

section 4Deploy the helloworld Application

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

  1. 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.


section 5Verify the Load-balanced helloworld Application Is Working Correctly

  1. 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
  2. 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?

    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'.

  3. 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.



section 6Housekeeping

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 and Deploying a Sample App 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.

  1. 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.

  2. 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 and Deploying a Sample App tutorial.

  3. (optional) To delete the cluster you created in the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes and Deploying a Sample App tutorial (named Tutorial Cluster in that tutorial):
    1. In the Console, open the navigation menu. Under Solutions, Platform and Edge, go to Developer Services and click Container Clusters.
    2. Click the name of the cluster you created for the tutorial.
    3. Click Delete Cluster.
      Description of the illustration
    4. Confirm that you want to delete the cluster.
  4. (optional) To delete the VCN you created in the Creating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes and Deploying a Sample App tutorial (named Tutorial-VCN in that tutorial):
    1. In the Console, open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
    2. Locate the VCN you created for the tutorial.
    3. Click the Actions icon beside the VCN you created, and then click Terminate.
      Description of the illustration
    4. Confirm that you want to terminate the VCN.

more informationWant to Learn More?