Skip to content

Part 1: Create Project

This is Part 1 of a multi-part, self paced quick start exercise.


What Will You Do

In part 1, you will

  • Create a new Project in your Org
  • Import a Kubernetes cluster into this Project using a "cluster blueprint"
  • Remotely access this cluster using the integrated browser based Zero Trust Kubectl

Estimated Time

Estimated time burden for this part is 15 minutes.


Kubernetes on Laptop

We have validated the following options. You can import any Kubernetes cluster as long as it is upstream Kubernetes compliant.


Microk8s

MicroK8s is a low-ops, minimal production Kubernetes distribution well suited for workstations and desktops. Ensure you use the stable channel for a reliable outcome.

Install

Follow the installation process for the operating system you are installing on. High level instructions are described below.

microk8s install --channel=1.21/stable

You should see something like the following

Launched: microk8s-vm
2021-10-05T16:48:03-07:00 INFO Waiting for automatic snapd restart...
microk8s (1.21/stable) v1.21.5 from Canonical✓ installed
microk8s-integrator-macos 0.1 from Canonical✓ installed
MicroK8s is up and running. See the available commands with `microk8s --help`.

Enable DNS

This service is required to supply address resolution services to Kubernetes. Without this service, the k8s operator pods will not be able to reach the SaaS controller.

microk8s enable dns

You should see something like the following.

Enabling DNS
Applying manifest
serviceaccount/coredns created
configmap/coredns created
deployment.apps/coredns created
service/kube-dns created
clusterrole.rbac.authorization.k8s.io/coredns created
clusterrolebinding.rbac.authorization.k8s.io/coredns created
Restarting kubelet
DNS is enabled

Verify

Once installation and configuration is complete, verify if everything is in order.

microk8s kubectl get po -A

You should see something like the following.

NAMESPACE     NAME                                      READY   STATUS    RESTARTS   AGE
kube-system   coredns-7f9c69c78c-jmdkx                  1/1     Running   0          36m
kube-system   calico-kube-controllers-f7868dd95-c295x   1/1     Running   0          37m
kube-system   calico-node-qq6hr                         1/1     Running   0          37m

Important

For microk8s, you need to prefix kubectl commands with microk8s.


Docker Desktop

Docker Desktop includes a standalone Kubernetes cluster that runs locally within your Docker instance. The Kubernetes cluster runs within a Docker container on your local system, and is only for local testing.

Resources

Ensure you have sufficient resources allocated to Docker Desktop to test and experience all parts of this exercise.

Resources for Docker Desktop

Enable Kubernetes

Enabling Kubernetes in Docker Desktop literally just requires "checking a box".

Docker Desktop with Kubernetes

Verify

Once enabled, ensure you are able to kubectl to the Kubernetes cluster running in Docker Desktop. In the example below, we are running Kubernetes v1.21.4.

kubectl get node -o wide

NAME             STATUS   ROLES                  AGE   VERSION   INTERNAL-IP    EXTERNAL-IP   OS-IMAGE         KERNEL-VERSION     CONTAINER-RUNTIME
docker-desktop   Ready    control-plane,master   22h   v1.21.4   192.168.65.4   <none>        Docker Desktop   5.10.47-linuxkit   docker://20.10.8

Step 1: Create Project

In this step, we will create a new project which will serve as a logically isolated "operating environment" (aka. sub tenant).

Note

Creating a project requires "Org Admin" privileges.

  • Login into your Org as an Org Admin
  • Create a new project called "desktop"

New Project

  • Switch context to this project by clicking on it.

View New Project


Step 2: Import Cluster

In this step, you will import your Kubernetes cluster into this project. We will use the "minimal" blueprint which comes with just the Kubernetes Management Operator components so that only minimal resources are deployed to the Kubernetes cluster.


Create

  • Click on New Cluster and Select "Import Existing Kubernetes Cluster"
  • Select "Datacenter/Edge" for Type
  • Select "Other" for Kubernetes Distribution
  • Provide a name such as "desktop" and Continue

Select Environment


Configure

In this step, you will provide the cluster's configuration

  • Ensure that the "minimal" cluster blueprint is selected and click on Continue.

Cluster Specification

You will be provided with a cryptographically unique "cluster bootstrap" yaml file.

  • Download the bootstrap yaml file

Cluster Specification


Step 3: Import Cluster

Use kubectl to apply the "cluster bootstrap" file on your Kubernetes cluster.

kubectl apply -f desktop-bootstrap.yaml

This will create a namespace for the k8s mgmt operator, download the container images, and register with the controller. This one time import process can take ~2 minutes and depends on the speed of your Internet connection to download the required images.

namespace/rafay-system created
podsecuritypolicy.policy/rafay-privileged-psp created
clusterrole.rbac.authorization.k8s.io/rafay:manager created
clusterrolebinding.rbac.authorization.k8s.io/rafay:rafay-system:manager-rolebinding created
clusterrole.rbac.authorization.k8s.io/rafay:proxy-role created
clusterrolebinding.rbac.authorization.k8s.io/rafay:rafay-system:proxy-rolebinding created
priorityclass.scheduling.k8s.io/rafay-cluster-critical created
role.rbac.authorization.k8s.io/rafay:leader-election-role created
rolebinding.rbac.authorization.k8s.io/rafay:leader-election-rolebinding created
customresourcedefinition.apiextensions.k8s.io/namespaces.cluster.rafay.dev created
customresourcedefinition.apiextensions.k8s.io/tasklets.cluster.rafay.dev created
customresourcedefinition.apiextensions.k8s.io/tasks.cluster.rafay.dev created
service/controller-manager-metrics-service created
deployment.apps/controller-manager created
configmap/connector-config created
configmap/proxy-config created
deployment.apps/rafay-connector created
service/rafay-drift created
validatingwebhookconfiguration.admissionregistration.k8s.io/rafay-drift-validate created

Step 4: Check Cluster Status

On the console, you will notice that the imported cluster would have registered itself and will start receiving instructions from the controller. You can also check the status of the mgmt operator pods on your cluster using kubectl.

kubectl get po -n rafay-system

You should see something like

NAME                                 READY   STATUS    RESTARTS   AGE
controller-manager-bf685d59f-kddqp   1/1     Running   0          59s
debug-client-7cb778456f-7x2nl        1/1     Running   0          59s
edge-client-56cbf89999-gh99s         1/1     Running   0          62s
rafay-connector-699d8dc5f8-6dqmt     1/1     Running   0          59s
relay-agent-84bc56d4dc-tm2kq         1/1     Running   0          60s

Once the k8s operator is operational, it will "establish and maintain a heartbeat" with the controller.

Successful Import


Troubleshooting

Here are some common conditions that can cause issues with the import process.

Blocking Firewall

The k8s operator pods installed in your cluster need to connect out on port 443 and establish a long running mTLS based control channel to the SaaS Controller. If you see the following pods in a Pending state for several minutes, you most likely have a network firewall blocking outbound connections. Installation will not proceed.

kubectl get po -n rafay-system

NAME                                READY  STATUS  RESTARTS  AGE
controller-manager-54db66978c-kp856  0/1   Pending  0        6m48s
rafay-connector-75649c86f-l876q      0/1   Pending  0        6m48s

To confirm this, you can use "kubectl logs"

kubectl logs rafay-connector<pod id> -n rafay-system

If you do not see a "connected to core" message, it is most likely a firewall or a DNS issue.

{"level":"info","ts":"2021-10-05T14:37:11.807Z","caller":"connector/connector.go:116","msg":"registering connector"}
{"level":"info","ts":"2021-10-05T14:37:11.818Z","caller":"connector/connector.go:123","msg":"registered connector"}
{"level":"info","ts":"2021-10-05T14:37:11.818Z","caller":"connector/connector.go:124","msg":"connecting to core"}
{"level":"info","ts":"2021-10-05T14:37:11.828Z","caller":"connector/connect.go:48","msg":"connecting","to":"control.rafay.dev:443"}
{"level":"info","ts":"2021-10-05T14:37:11.954Z","caller":"connector/connector.go:131","msg":"connected to core"}

Solution White list the Controller's IPs and import again.


No DNS

Ensure your cluster has DNS configured and enabled. This is required for the pods to resolve the SaaS Controller on the Internet in order to connect to it.


Resources

Ensure your cluster has sufficient resources available for pods to become operational.


Network Bandwidth

Ensure you have a resonable and stable connection to the Internet.


Recap

Congratulations! At this point, you have successfully imported an existing Kubernetes cluster to your project. You are ready to progress to the next part.