Quick Start¶

Prerequisites¶

Creating a Kubernetes cluster¶

The Catalyst Cloud dashboard allows you to create, manage and monitor the current status of your clusters.

From the Clusters page under the Container Infra tab, you will see the following:

This page gives you an overview of your clusters, their status and how many clusters you have, measured against your quota.

To create a new cluster, click the + Create Cluster button:

Pick a Name for your new cluster, and choose the latest Cluster Template version available from the drop-down list.

Once that is done your screen should look something like this:

Next, select the Size tab to configure the size and number of nodes in the cluster.

There are two types of nodes in Catalyst Cloud Kubernetes clusters: Control Plane Nodes (formerly referred to as Master Nodes), and Worker Nodes.

Control Plane Nodes are where the Kubernetes control plane is hosted, and Worker Nodes run the container deployments uploaded to Kubernetes.

You may create any number of Worker Nodes, however Control Plane Nodes must be created with an uneven number e.g. 1, 3 or 5.

In the example below, the cluster will be created with 1 Control Plane Node and 3 Worker Nodes.

The flavors of the Control Plane Nodes and Worker Nodes can also be configured individually. For this guide we will use the default values.

Select the Network tab to configure the cluster’s network access.

To enable access to the Kubernetes API from the public Internet, select ‘Accessible with public floating IP’ from the Floating IP drop-down list. For this guide, we will leave the Allowed CIDRs field empty.

That is everything you need to configure for this guide, so press the Submit button to create the cluster.

You will be returned to the Clusters page, where you can monitor the state of your Kubernetes clusters. Our new cluster should be listed, in CREATE_IN_PROGRESS state. Refresh the page periodically to see the updated cluster status.

Creating a new Kubernetes cluster can take up to 20 minutes, depending on the size of the cluster you are trying to build.

Once the cluster has reached the CREATE_COMPLETE state, it is now up and running, and you can start using it.

You can now download the kubeconfig file for the cluster using the Download Kubeconfig button.

Interacting with Kubernetes¶

export KUBECONFIG="${HOME}/Downloads/quickstart1_kubeconfig"

mkdir -p "${HOME}/.kube" && mv "${HOME}/Downloads/quickstart1_kubeconfig" "${HOME}/.kube/config"

$Env:KUBECONFIG = $env:USERPROFILE\Downloads\quickstart1_kubeconfig

set KUBECONFIG=%homedrive%%homepath%\Downloads\quickstart1_kubeconfig

$ kubectl cluster-info
Kubernetes control plane is running at https://192.0.2.1:6443
CoreDNS is running at https://192.0.2.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Accessing the Kubernetes dashboard¶

Now that we have kubectl available, we can access the Kubernetes dashboard.

Linux / macOSWindows (PowerShell)Windows (Command Prompt)

In the currently open terminal (with your OpenRC file sourced), run the following command to fetch the authentication token from the environment, and copy it to the clipboard.

We will use this once the dashboard is open.

echo $OS_TOKEN

Now run the following command in the same terminal window:

kubectl proxy

This starts a proxy session which allows you to access the dashboard.

$ kubectl proxy
Starting to serve on 127.0.0.1:8001

Once the proxy is running, open the following URL in your browser:

http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:https/proxy

You will be presented with a login screen, as shown below. Select Token as the authentication type and paste in the authentication token acquired in the previous steps.

Press Sign in to login, and you should now have the Kubernetes dashboard open in your browser.

Running a basic application¶

Let’s try creating a deployment for a basic application on Kubernetes.

First, click the + button in the top right of the dashboard to open the Create new resource form.

Select Create from input, and paste the following YAML into the form.

This YAML creates a new deployment called quickstart-nginx, which consists of a single nginx web server, serving the default test page via HTTP (port 80).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: quickstart-nginx
  labels:
    app: quickstart-nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: quickstart-nginx
  template:
    metadata:
      labels:
        app: quickstart-nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

The filled in form should look like this:

Press Upload to create the deployment.

You will now directed back to the home page, where the new deployment will be tracked in real time:

Let’s check that our new application is working properly. This application is not accessible from the Internet, so we will need to create a port forward from the local machine to the application in the cluster.

Since the terminal window we have been using is currently running the kubectl proxy command for the Kubernetes dashboard, open a new terminal window. Make sure to source your OpenRC file, and set the KUBECONFIG environment variable (as shown in Configuring kubectl).

Then, run the following command to create the port forward to the application:

kubectl port-forward deployment/quickstart-nginx 8888:80

This maps port 80 from the application to port 8888 on the local machine.

$ kubectl port-forward deployment/quickstart-nginx 8888:80
Forwarding from 127.0.0.1:8888 -> 80
Forwarding from [::1]:8888 -> 80

You should now be able to open the following URL and access the application:

http://localhost:8888

If the following page is returned, congratulations! Your first deployment on a Catalyst Cloud Kubernetes cluster is working correctly.