Oracle by Example brandingCreating a Cluster with Oracle Cloud Infrastructure Container Engine for Kubernetes and Deploying a Sample App

section 0Before You Begin

This 10-minute tutorial shows you how to:

  • create a new cluster with default settings and new network resources
  • create a node pool
  • download the kubeconfig file for the cluster
  • verify you can access the cluster using kubectl and the Kubernetes Dashboard
  • deploy a sample app to the cluster

Background

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.

In this tutorial, you use default settings to define a new cluster. When you create the new cluster, new network resources for the cluster are created automatically, along with a node pool and three worker nodes. You'll then download the Kubernetes configuration file for the cluster (the cluster's 'kubeconfig' file). The kubeconfig file enables you to access the cluster using kubectl and the Kubernetes Dashboard. Finally, you'll deploy a sample helloworld app to the cluster.

What Do You Need?

  • An Oracle Cloud Infrastructure username and password.
  • Within the root compartment of your tenancy, a policy statement Allow service OKE to manage all-resources in tenancy must be defined to give Container Engine for Kubernetes access to resources in the tenancy.
  • Within your tenancy, there must already be a compartment to contain the necessary network resources (VCN, subnets, internet gateway, route table, security lists). If such a compartment does not exist already, you will have to create it before starting this tutorial.
  • At least three compute instances must be available in the tenancy to complete this tutorial as described. Note that if only one compute instance is available, it is possible to create a cluster with a node pool that has a single subnet and a single node in the node pool. However, such a cluster will not be highly available.
  • To create and/or manage clusters, you must belong to one of the following:
    • The tenancy's Administrators group.
    • A group to which a policy grants the appropriate Container Engine for Kubernetes permissions. As you'll be creating a cluster and associated network resources during the tutorial, policies must also grant the group the necessary permissions to create those network resources (which will include the VCN_READ and SUBNET_READ permissions).
  • Before you download the kubeconfig file later in the tutorial, you must have already done the following (if you haven't, or you're not sure, see the Downloading a kubeconfig File to Enable Cluster Access topic in the Container Engine for Kubernetes documentation):
    • generated an API signing key pair
    • added the public key value of the API signing key pair to the User Settings for your username
    • installed and configured the Oracle Cloud Infrastructure CLI
  • You must have installed and configured the Kubernetes command line tool kubectl. If you haven't done so already, see the kubectl documentation.

section 1Starting OCI

  1. In a browser, go to the url you've been given to log in to Oracle Cloud Infrastructure.
  2. Description of the illustration
  3. Specify a tenant in which you have the appropriate permissions to create clusters. You inherit these permissions in one of the following ways:
    • By belonging to the tenancy's Administrators group.
    • By belonging to another group to which a policy grants the appropriate Container Engine for Kubernetes permissions. As you'll be creating a cluster and associated network resources during the tutorial, policies must also grant the group the necessary permissions to create those network resources (which will include the VCN_READ and SUBNET_READ permissions).
  4. Enter your username and password.

section 2Define Cluster Details

  1. In the Console, open the navigation menu. Under Solutions, Platform and Edge, go to Developer Services and click Container Clusters.
  2. Choose a Compartment that you have permission to work in, and in which you want to create both the new cluster and the associated network resources, and then click Clusters.
  3. Description of the illustration
  4. On the Clusters page, click Create Cluster. The examples shown in this tutorial assume you give the new cluster the name Tutorial Cluster.
    Description of the illustration
  5. In the Cluster Creation dialog, change the placeholder value in the Name field and enter Tutorial Cluster instead.
  6. Select the Quick Create option to indicate you want to create a new cluster with default settings, along with new network resources for the new cluster.
  7. Description of the illustration
  8. Click Create to create the new network resources and the new cluster.
  9. Description of the illustration
    You see the different network resources being created for you.
    Description of the illustration
  10. Click Close to return to the Console.
  11. Description of the illustration
    The new cluster is shown on the Cluster Details page. When it has been created, the new cluster has a status of Active.
    Description of the illustration
  12. Scroll down to see details of the new node pool that has been created, along with details of the new worker nodes (compute instances).
  13. Description of the illustration

section 3Download the kubeconfig File for the Cluster

  1. Confirm that you've already done the following:
    • Generated an API signing key pair.
    • Added the public key value of the API signing key pair to the User Settings for your username.
    • Installed and configured the Oracle Cloud Infrastructure CLI.

    If you haven't done one or more of the above, or you're not sure, see the Downloading a kubeconfig File to Enable Cluster Access topic in the Container Engine for Kubernetes documentation.

  2. With the Cluster Details page showing the Tutorial Cluster, click Access Kubeconfig to display the How to Access Kubeconfig dialog box.
    Description of the illustration
  3. In a terminal window, create a directory to contain the kubeconfig file, giving the directory the expected default name  and location of $HOME/.kube. For example, on Linux, enter the following command (or copy and paste it from the How to Access Kubeconfig dialog box): 
  4. $ mkdir -p $HOME/.kube
  5. Run the Oracle Cloud Infrastructure CLI command to download the kubeconfig file and save it with the expected default name and location of $HOME/.kube/config. This name and location ensures the kubeconfig file is accessible to kubectl and the Kubernetes Dashboard whenever you run them from a terminal window. For example, on Linux, enter the following command (or copy and paste it from the How to Access Kubeconfig dialog box):
    $ oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.phx.aaaaaaaaae... --file $HOME/.kube/config
    where ocid1.cluster.oc1.phx.aaaaaaaaae... is the OCID of the current cluster. For convenience, the command in the How to Access Kubeconfig dialog box already includes the cluster's OCID.
  6. Click Close to close the How to Access Kubeconfig dialog.

section 4Verify kubectl and Kubernetes Dashboard Access to the Cluster

  1. Confirm that you've already installed kubectl. If you haven't done so already, see the kubectl documentation.
  2. Verify that you can use kubectl to connect to the new cluster you've created. In a terminal window, enter the following command:
    $ 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.11.1
    129.146.122.19     Ready    node    1d    v1.11.1
    129.146.85.6       Ready    node    1d    v1.11.1
    
  3. Verify that you can use the Kubernetes Dashboard to connect to the cluster:
    1. In a terminal window, enter the following command:
      $ kubectl proxy
    2. Open a new browser window and go to http://localhost:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/ to display the Kubernetes Dashboard.
      Description of the illustration
    3. Select the Kubeconfig option, click Choose kubeconfig file, and select the kubeconfig file that you downloaded earlier.
    4. Click Sign In.
    5. Click Overview to see that Kubernetes is the only service running in the cluster.
      Description of the illustration
    6. You've confirmed that the new cluster is up and running as expected. You can now deploy an application to the cluster.


section 5Deploy a Sample App to the Cluster

  1. In a terminal window, deploy the sample helloworld application to the cluster by entering:
    $ kubectl create -f https://raw.githubusercontent.com/karthequian/kubernetesHelloworld/master/hello.yaml
  2. Messages confirm that the deployment hello-k8s-deployment and the service hello-k8s-service have both been created.

  3. Return to the browser displaying the Kubernetes Dashboard. The Overview page now shows the helloworld sample application has been deployed (as hello-k8s-deployment) on one pod, on one node in the cluster.
    Description of the illustration
  4. Assemble the url to access the helloworld application, in the form http://<node-address>:<port-number>. Obtain the values of <node-address> and <port-number> from the Kubernetes Dashboard as follows:
    • To find out the <node-address>, click Pods to see information about the pod running the helloworld application, and obtain the address of the node running the hello-k8s-deployment from the Node column. For example, 129.146.102.157.
    • To find out the <port-number>, click Services to see information about the hello-k8s-service, and obtain the port that the service is running on (in addition to port 80) from the Internal endpoints column. For example, port 32570.
  5. Open a new browser window and enter the url to access the helloworld application in the browser's URL field. For example, the full url might look like http://129.146.102.157:32570

    When the browser loads the page, the page shows 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'.

  6. 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 onto a node in the new cluster, and verified that the application is working as expected.


section 6Housekeeping (optional)

Having completed the tutorial, if you want to free up Oracle Cloud Infrastructure resources, you can now delete the VCN and the cluster that you created. On the other hand, it's a good idea to retain them (especially the VCN) for your own testing purposes. If you intend to follow the Pulling an Image from Oracle Cloud Infrastructure Registry when Deploying a Load-Balanced Application to a Cluster tutorial, definitely don't delete the VCN and the cluster because you will use them in that tutorial.

  1. (optional) Go back to the browser window with the Cluster Details page showing the Tutorial Cluster, click Delete Cluster and confirm that you want to delete the Tutorial Cluster you created.
    Description of the illustration
  2. (optional) Delete the VCN created during the 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 during this tutorial.
    3. Click the Actions icon beside the VCN, and then click Terminate.
      Description of the illustration
    4. Confirm that you want to terminate the VCN.

more informationWant to Learn More?