Getting Started with Wercker Clusters

Using Wercker Clusters (Limited Availability)

Prerequisites

Before you can use Wercker Clusters to create a Kubernetes cluster:

  • You must have been invited to use this Limited Availability feature. To request an invitation, go to wercker.com.
  • You must have a Wercker username and a Wercker authentication token. If you don't have an authentication token already, see How to get a Wercker Authentication token.
  • You must know the Oracle Cloud Infrastructure (OCI) credentials for an existing OCI tenancy, and those credentials must have full admin access to a compartment in the tenancy (or if no compartments exist, the credentials must have full admin access to the tenancy itself).
  • You must have installed and configured the Kubernetes command line tool kubectl (see the Kubernetes documentation).

What is Wercker Clusters?

Wercker Clusters is a fully-managed, scalable, and highly available service that you can use to deploy your containerized applications to the cloud. You specify the compute resources that your applications require, and Wercker Clusters provisions them on Oracle Cloud Infrastructure (OCI) in an existing OCI tenancy.

Wercker Clusters uses standard Kubernetes - the open-source system for automating deployment, scaling, and management of containerized applications across clusters of hosts. Kubernetes groups containers that make up an application into logical units (called pods) for easy management and discovery.

When to use Wercker Clusters?

Use Wercker Clusters when your development team wants to reliably build, deploy, and manage cloud-native applications. Using Wercker Clusters, you can define and create Kubernetes clusters on Oracle Cloud Infrastructure (OCI) using the Wercker Web UI and the Wercker Clusters REST API. You can access the clusters you have created using the Kubernetes command line (kubectl) and the Kubernetes Dashboard. 

About Kubernetes clusters and nodes

A Kubernetes cluster is a group of nodes. The nodes are the machines running applications. Each node can be a physical machine or a virtual machine. The node's capacity (its number of CPUs and amount of memory) is defined when the node is created. A cluster can be organized into namespaces, to divide the cluster's resources between multiple uses. A cluster comprises:

  • a master node (for high availability, the master node might actually be a number of nodes fronted by a load balancer)
  • one or more worker nodes (sometimes known as minions)

The master node in a cluster runs a number of processes:

  • kube-apiserver to support API operations via the Kubernetes command line tool (kubectl) and the REST API
  • kube-controller-manager to manage different Kubernetes components (for example, replication controller, endpoints controller, namespace controller, and serviceaccounts controller)
  • kube-scheduler to control where in the cluster to run jobs
  • etcd to store the cluster's configuration data

Each worker node runs two Kubernetes processes:

  • kubelet to communicate with the master node
  • kube-proxy to handle networking

Each worker node also runs the Docker runtime.

The Kubernetes processes running on the master node are collectively referred to as the Kubernetes Control Plane. Together, the Control Plane processes monitor and record the state of the cluster and distribute requested operations between the nodes in the cluster.

Where an application running on a worker node comprises multiple containers, the containers are located in a single pod. The containers in the pod share the same networking namespace and the same storage space, and can be managed as a single object by the Kubernetes Control Plane.

A node pool is a subset of machines within a cluster that all have the same configuration. Node pools enable you to create pools of machines within a cluster that have different configurations. For example, you might create one pool of nodes in a cluster as virtual machines, and another pool of nodes as bare metal machines. A cluster must have a minimum of one node pool, but a node pool need not contain any worker nodes.

What is a Kubernetes manifest?

A Kubernetes manifest comprises instructions in a yaml or json file that specify how to deploy an application to the nodes in a Kubernetes cluster. The instructions include information about the Kubernetes deployment, the Kubernetes service, and other Kubernetes objects to be created on the cluster.

The parameters to include in a Kubernetes manifest file are described in the Kubernetes documentation.

How to create a Kubernetes cluster using Wercker Clusters

When you use Wercker Clusters to create a new Kubernetes cluster, you specify credentials for the existing OCI tenancy where you want to create the cluster. The credentials are saved as a named credential set that you can reuse if you want to create another Kubernetes cluster. As well as the OCI credentials, whenever you create a new cluster you also specify a resource profile that determines the number of CPUs and the amount of memory assigned to each worker node in the new cluster.

Tip: You can create a named credential set in advance by clicking Cloud Credentials on the Clusters page.

To create a Kubernetes cluster using Wercker Clusters:

  1. In the Wercker UI, display the Clusters page.
  2. Click Create Cluster.
  3. Specify a name for the new cluster, the Wercker organization to which it belongs, the version of Kubernetes that you want to run on the manager node, and click Next.
  4. Specify the credentials for the existing OCI tenancy in which to create the new cluster:
    • If the credentials have been saved previously as a named credential set, you can simply select the set from the Cloud Credentials list and specify the following additional properties:
      Property Specify
      Compartment ID (optional) The OCID of the compartment in the OCI tenancy in which to create the cluster. A compartment is a collection of related resources (such as cloud networks, compute instances, or block volumes).
      If you specify a compartment, the OCI credentials you specify must have full admin access to the compartment.
      If you don't specify a compartment (or if no compartments exist in the tenancy), Wercker Clusters creates one for you with a name in the format oke-cmprtmnt-oke-<string>. In this case, the OCI credentials you specify must have full admin access to the OCI tenancy itself.
      For example:
      ocid1.compartment.oc1..aaaaaaaarvdfa72n...
      Public SSH Key (optional) The public key of an SSH public/private key pair to enable you to have SSH access to the worker nodes in the cluster. The public key is installed on all worker nodes in the cluster.
      Note that if you don't specify a public SSH key, Wercker Clusters will provide one. However, since you won't have the corresponding private key, you will not have SSH access to the worker nodes.
      For example:
      ssh-rsa MIIBIjANBgkqhkiG9w0BAQE...
    • If the credentials have not been saved as a named credential set, enter the OCI credentials, tenancy information, and an SSH key to use when accessing worker nodes as follows:
      Property Specify
      Organization The Wercker organization to which the named credential set will belong.
      Only Wercker users belonging to this organization will be able to select this named credential set.
      For example:
      acme-dev
      Name A name of your choice for this set of credentials. The name you enter will appear in the Cloud Credentials list.
      For example:
      OCI_CLOUD_CONFIG
      User OCID The OCID of the user with which to log into the tenancy.
      For example:
      ocid1.user.oc1..aaaaaaaalhjqi7...
      Tenancy OCID The OCID of the OCI tenancy. The tenancy OCID is shown at the bottom of the OCI console Home page.
      For example:
      ocid1.tenancy.oc1..aaaaaaaaba3kcr4...
      Fingerprint The fingerprint of the public key.
      For example:
      12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef
      Private Key (PEM Format) The private key to access the OCI API.
      For example:
      -----BEGIN RSA PRIVATE KEY-----
      AAAAB3NzaC1yc2EAAAADAQABAAABAQDGw...
      -----END RSA PRIVATE KEY-----

      Tip: When you create the cluster, the credentials you've entered are saved as a named credential set with the name you specified. If you create another cluster in the same tenancy, you can select that named credential set rather than re-entering the credentials. The named credential set is available to all members of the organization.

      For more information about OCI credentials, see the OCI documentation.

  5. Specify the size of the cluster to create. You can choose from a number of predetermined cluster configurations, or define a custom cluster configuration by specifying the number of worker nodes in each availability domain, and the shape of each worker node.
  6. Specify the operating system and Kubernetes version to run on each worker node.
  7. Click Launch to create the cluster.

Wercker Clusters creates the cluster and displays it in the list of clusters. Wercker Clusters also creates a Kubernetes configuration file called kubeconfig that you use to access the cluster using kubectl and the Kubernetes Dashboard.

You can also use the Wercker REST API to create a cluster. See Create Cluster in the REST API documentation.

How to modify a Kubernetes cluster using Wercker Clusters

You can use Wercker Clusters to modify the node pool details of existing Kubernetes clusters.

You can change:

  • the number of node pools in a cluster (a cluster must have a minimum of one node pool)
  • the number of worker nodes in a node pool (a node pool can have zero worker nodes)
  • the number of availability domains associated with a node pool

However, note that you cannot change:

  • the name of the cluster
  • the shape of the nodes in an existing node pool
  • the operating system running on worker nodes
  • the version of Kubernetes running on worker nodes

To modify an existing Kubernetes cluster:

  1. Use the Wercker REST API to modify an existing Kubernetes cluster. See Update Pools in a Cluster in the REST API documentation.

How to delete a Kubernetes cluster using Wercker Clusters

To delete a Kubernetes cluster using Wercker Clusters:

  1. In the Wercker UI, display the Clusters page.
  2. Click Grouped.
  3. Click the Delete icon beside the name of the cluster to delete, and confirm that you want to delete it.

You can also delete a cluster:

  • Using the Delete button on the cluster's Configuration tab.

  • Using the Wercker Clusters REST API. See Delete a Specific Cluster in the REST API documentation.

How to access a cluster using kubectl

Before you can use the Kubernetes command line tool kubectl, you need to specify the cluster on which kubectl is to perform operations. When you create a cluster, Wercker Clusters creates a Kubernetes configuration file for the cluster called kubeconfig. The cluster's kubeconfig file provides the details that kubectl requires to access the cluster.

To access a cluster using kubectl:

  1. In the Wercker UI, display the Clusters page.
  2. Click the name of the cluster you want to access using kubectl. The Summary tab shows details of the cluster.
  3. Display the Get Started tab, and download the cluster's kubeconfig configuration file by clicking Download kubeconfig File.
  4. Save the file in a location accessible to kubectl (for example, in ~/Downloads/kubenetes).
  5. In a terminal window:
    1. Set the KUBECONFIG environment variable to the name and location of the kubeconfig file. For example, in a Linux environment, type export KUBECONFIG=~/Downloads/kubeconfig
    2. Verify that Kubernetes is available and that it can connect to the cluster by typing kubectl version

      The versions of Kubernetes running on the client and on the master node are shown.

  6. Use kubectl to perform operations on the cluster.

You can also use the Wercker Clusters REST API to get a cluster's kubeconfig configuration file by making a GET request to the /api/v3/clusters/${resourceOwnerId}/${id}/kubeconfig endpoint.

How to start the Kubernetes Dashboard

Kubernetes Dashboard is a web-based user interface that you can use as an alternative to the Kubernetes kubectl command line tool to:

  • deploy containerized applications to a Kubernetes cluster
  • troubleshoot your containerized applications

You use the Kubernetes Dashboard to get an overview of applications running on a cluster, as well as to create or modify individual Kubernetes resources. The Kubernetes Dashboard also reports the status of Kubernetes resources in the cluster, and any errors that have occurred.

In contrast to the Kubernetes Dashboard, Wercker Clusters enables you to create and delete Kubernetes clusters and node pools, and to manage the associated compute, network, and storage resources. 

To start the Kubernetes Dashboard:

  1. In a terminal window:
    1. If you haven't already done so, set the KUBECONFIG environment variable to the name and location of the kubeconfig file. For example, in a Linux environment, type export KUBECONFIG=~/Downloads/kubeconfig
    2. Verify that Kubernetes is available and that it can connect to the cluster by typing kubectl version

      The versions of Kubernetes running on the client and on the master node are shown.

    3. Type kubectl proxy to start the Kubernetes Dashboard.
  2. Open a browser and go to http://localhost:8001/ui to display the Kubernetes Dashboard.
  3. Click Overview to see the applications deployed on the cluster.

How to deploy a sample nginx app on a cluster using kubectl

Having created a Kubernetes cluster using Wercker Clusters, you'll typically want to try it out by deploying an application on the nodes in the cluster. For convenience, the Wercker UI includes a Get Started page that makes it easy to:

  • download the kubeconfig configuration file that's been created for the cluster
  • download and deploy a sample nginx application using the Kubernetes command line tool kubectl from the instructions in a manifest file
  • start the Kubernetes Dashboard to view the deployed application running on nodes in the cluster

To deploy the sample nginx application:

    1. In the Wercker UI:
      1. Display the Clusters page.
      2. Click the name of the cluster on which to deploy your first app. The Summary tab shows details of the cluster.
      3. Display the Get Started tab, and download the cluster's kubeconfig configuration file by clicking Download kubeconfig File.
      4. Save the file in a location accessible to kubectl (for example, in ~/Downloads/kubenetes).
    2. In a terminal window:
      1. If you haven't already done so, set the KUBECONFIG environment variable to the name and location of the kubeconfig file. For example, in a Linux environment, type export KUBECONFIG=~/Downloads/kubeconfig
      2. Verify that Kubernetes is available and that it can connect to the cluster by typing kubectl version

        The versions of Kubernetes running on the client and on the master node are shown.

      3. Deploy the application by typing kubectl create -f https://k8s.io/docs/tasks/run-application/deployment.yaml

        Tip: If the command fails to connect to https://k8s.io/docs/tasks/run-application/deployment.yaml , go to the url in a browser and download the manifest file deployment.yaml to a local directory. Repeat the kubectl create command and specify the local location of the deployment.yaml file.

    3. Use the Kubernetes Dashboard to confirm that the sample application has deployed successfully:
      1. If you haven't already done so, set the KUBECONFIG environment variable to the name and location of the kubeconfig file. For example, in a Linux environment, type export KUBECONFIG=~/Downloads/kubeconfig
      2. Type kubectl proxy to start the Kubernetes Dashboard.
      3. Open a browser and go to http://localhost:8001/ui to display the Kubernetes Dashboard.
      4. Click Overview to see the applications deployed on the cluster.

You can see the nginx sample app has been deployed as two pods, on two nodes in the cluster. 

Example: Build an application in Wercker, push it to Wercker Releases registry, and deploy it to a Kubernetes cluster created using Wercker Clusters

In this example, you start by forking an existing hello-world application on GitHub. Having built it as a Docker image in Wercker, you push the image to the Wercker Releases registry. Finally, you deploy it as Docker container to the nodes in a Kubernetes cluster that you've created using Wercker Clusters.

The hello-world application on GitHub comprises three files:

  • main.go contains the application code.
  • wercker.yml describes four different pipelines that you will chain into a workflow, and the steps executed by each pipeline.
  • kubernetes.yml.template defines how to deploy the application on the cluster (a Kubernetes manifest file is created from this template). In this case, the application is deployed as a Kubernetes deployment, and a Kubernetes service is exposed so the application can be accessed. The service is created with a type of "LoadBalancer" so that a load balancer is created the first time the service is deployed (for more information about load balancers, see How to create a load balancer).

Before you start:

  • You must already have a Wercker username and a Wercker authentication token. If you don't have an authentication token already, see How to get a Wercker Authentication token.
  • You must have access to a Kubernetes cluster that was created using Wercker Clusters (see How to create a Kubernetes cluster using Wercker Clusters).
  • You must belong to the Owners group of the organization that owns the repository in the Wercker Releases registry to which the image is pushed, and from which it is pulled.
  • It's recommended that you've created a new Wercker organization to own the application (for example, called your_name-hello-world).

To build, push, and deploy the hello-world application:

  1. Log in to your GitHub account and fork the hello-world project at https://github.com/wercker/oke_examples/tree/master/hello_world.
  2. In the Wercker UI, display the Clusters page and click the name of the cluster on which to deploy the hello-world application.
  3. Display the Get Started tab and download the cluster's kubeconfig configuration file by clicking Download kubeconfig File.
  4. In a terminal window:
    1. If you haven't already done so, set the KUBECONFIG environment variable to the name and location of the kubeconfig file. For example, in a Linux environment, type export KUBECONFIG=~/Downloads/kubeconfig
    2. Verify that Kubernetes is available and that it can connect to the cluster by typing kubectl cluster-info
    3. Make a note of the address and port number of the master node returned by the kubectl cluster-info command as you'll need them later.
  5. In the Wercker UI, select Add application from the + menu and complete the wizard as follows:
    1. Specify GitHub as the Git provider.
    2. Select the GitHub repository into which you forked the hello-world app, and click Use selected repo.
    3. Select the Wercker organization to own the new application (for example, <your_name>-hello-world), and click Use selected owner.
    4. Select wercker will checkout the code without using an SSH key, click Next Step, and then click Finish.

      The Runs tab of the Pipelines page is displayed.

  6. Display the Workflows tab, which shows the build pipeline already created by default. In the case of the hello-world application, the build pipeline pulls the application from GitHub and builds it.
  7. Create three additional pipelines by clicking Add new pipeline, entering the following details, and then clicking Create:
    Name:
    YML Pipeline name:
    Hook type:
    Notes
    push-release
    push-release Default Pushes the generated Docker image to the registry (using a Wercker "internal step").
    inject-secret
    inject-secret Default Inserts the Docker registry credentials into the Kubernetes cluster so that it can pull the image from the registry.
    deploy-to-cluster
    deploy-to-cluster Default Creates a Kubernetes deployment and Kubernetes service to expose the app on the Kubernetes cluster.

    The three new pipelines are shown in the Pipelines section of the Workflows tab.

  8. In the Editor section of the Workflows tab, which contains the build pipeline by default, add the other pipelines to the workflow in the following order :
    1. Click the + symbol to the right of build, select push-release from the Execute pipeline list, and click Add.
    2. Click the + symbol to the right of push-release, select inject-secret from the Execute pipeline list, and click Add.
    3. Click the + symbol to the right of inject-secret, select deploy-to-cluster from the Execute pipeline list, and click Add.
  9. Display the Environment tab and define the following environment variables by entering Key and Value details as shown:
    Key Value Notes
    KUBERNETES_MASTER https://<master_node_IP>:<port>

    For example:

    https://123.456.78.90:443

    The full address (including https://) and port of the master node returned by kubectl cluster-info command.
    KUBERNETES_TOKEN <Wercker_token>

    For example:

    fbff5d3f9dfd788...
    The Wercker authentication token for your Wercker username.
    DOCKER_REGISTRY wcr.io

    For example:

    wcr.io
    The address of the Wercker Releases registry.
    DOCKER_EMAIL <email_address>

    For example:

    jdoe@acme.com
    An email address (it doesn't matter what you specify) is required to successfully inject the secret into the Kubernetes cluster so Kubernetes knows how to pull the image from the Wercker Releases registry.
    DOCKER_USERNAME <Wercker_username>

    For example:

    john-smith
    Your Wercker username, which is used to log in to the Wercker Releases registry.
    DOCKER_REPO wcr.io/<Wercker_org_name> /<app_name>

    For example:

    wcr.io/john- org/hello-world
    The location of the hello-world application in the Wercker Releases registry, from where the Kubernetes cluster is to obtain the image. Note that to successfully push and pull images to and from the repository you specify, you must belong to the organization's Owners group.
  10. In GitHub, edit the main.go file, change the message output by the HelloWorld function to a message of your choice, and commit the change.

    When you commit the change, a build is triggered in Wercker.

  11. In the Wercker UI, display the Runs tab and watch the workflow as:
    • the build gets triggered
    • a Docker image is created and pushed to the Wercker Releases registry
    • credentials are inserted into the Kubernetes cluster
    • the application is deployed to the cluster
  12. In a terminal window, type kubectl get all to monitor the application's deployment to the cluster . The first time the application is deployed, it might take a while for the Kubernetes worker nodes to download the image. Repeat kubectl get all until you see an external IP address for the load balancer for the svc/hello-world service.

    Tip: To watch the progress of the load balancer creation, type kubectl get service hello-world --watch

  13. Copy the external IP address for the svc/hello-world service load balancer (for example, 123.456.78.99) into a browser, along with the port number (for example, 8080).

    The browser shows the message you specified for the HelloWorld function to output, indicating that the application is now running behind the load balancer.

  14. Clean up the cluster by typing kubectl delete deployment,service hello-world to remove the application deployments and the load balancer.

How to get a Wercker Authentication token

Before you can use Wercker Clusters to create and manage Kubernetes clusters, you must already have a Wercker username and a Wercker authentication token. If you haven't got a Wercker authentication token, or you've forgotten it, or you're not sure, you can create a new authentication token. You only see the value of the authentication token when you create it, so be sure to copy the token value to a secure location immediately.

Tip: If you do lose or forget the value of the authentication token, you can always create a new authentication token. There's no limit to the number of authentication tokens you can create.

To create a new Wercker authentication token:

  1. Log in to https://app.wercker.com using the username and password that you provided while creating an account with Wercker.
  2. Click your avatar icon in the top right-hand corner, select Settings to display the Profile page, and select Personal token from the left-hand menu to display the Personal tokens page.
  3. Enter a name for the new Wercker authentication token (for example, my-first-token), and click Generate.

    The value of the new token is shown. For example, fbff5d3f9dfd788... (abbreviated for readability).

  4. Copy the token value and keep it in a secure location, as you won't be able to see it again.
  5. Click Done. The name of the token appears in your list of personal tokens, along with the last few characters of the token value.