Command line access

info

Access to the PAAS kubernetes API with kubectl requires that you are on a Sikt network.

To investigate the status status of your application in the Platon PaaS, you will sometimes need to use the kubectl command line utility. This application allows you to examine the status of the various resources your application haas in the Platon PaaS.

Installing kubectl

You can find installation instructions for kubectl in the Kubernetes documentation.

After you have installed kubectl you can verify that it works by running kubectl in your terminal. This should give you some usage instructions:

$ kubectl
kubectl controls the Kubernetes cluster manager.

Find more information at: https://kubernetes.io/docs/reference/kubectl/overview/
[...]

Installing Platon kubectl authentication helper

Platon has an authentication helper for kubectl (platon-kubectl-auth). This helper is a authentication plugin for kubectl that automates the process of issuing a token for the Kubernetes cluster. When you need a new token, it executes a login to the Platon PaaS console in your browser and then retrieves a token for the Kubernetes cluster.

The authentication helper must be installed as platon-kubectl-auth in a directory that is on your executable search path.

1. Download the latest version for your operating system from: https://gitlab.sikt.no/platon/platon-kubectl-auth/-/releases
2. Save it as platon-kubectl-auth in your executable path. E.g. if you have ${HOME}/bin on your executable path ($PATH), and it was downloaded to ${HOME}/Downloads:

   mv "${HOME}/Downloads/platon-kubectl-auth-0.2-linux-amd64" "${HOME}/bin/platon-kubectl-auth"

3. Make the downloaded file executable. E.g.:

   chmod +x "${HOME}/bin/platon-kubectl-auth"

4. Verify that you can run the platon-kubectl-auth command. Run the platon-kubectl-auth command manually to verify that it is available in your executable search path. It should fail with an error message indicating that it is supposed to be run through kubectl. E.g.:

   $ platon-kubectl-auth
   platon-kubectl-auth: Failed to determine Kubernetes server: KUBERNETES_EXEC_INFO environment variable not set -- make sure to run this command through kubectl

info

If you cannot use the Platon kubectl authentication helper, you can still access the Kubernetes cluster. To do this, follow the instructions below, but select a specific cluster in the "Target cluster" dropdown on the Kubeconfig page. This gives you a configuration for a single cluster, with a token in the configuration.

Configuring kubectl

Before you can access the Kubernetes cluster, you need to configure it to talk to the Platon Paas cluster.

Visit the Kubeconfig page on Platon PaaS console to get configuration for kubectl. You can either download a kubeconfig file or run the shell commands to configure kubectl.

If you download a kubeconfig file, it must be saved as ${HOME}/.kube/config. E.g. if the file is downloaded to ${HOME}/Downloads/kubeconfig:

mkdir "${HOME}/.kube"
mv "${HOME}/Downloads/kubeconfig" "${HOME}/.kube/config"

Or run the shell commands:

$ kubectl config set-cluster paas2 --server=https://38B1D1609274C2E9AB111FAB92F8B185.gr7.eu-north-1.eks.amazonaws.com
Cluster "paas2" set.
$ kubectl config set clusters.paas2.certificate-authority-data LS0tL[...]
Property "clusters.paas2.certificate-authority-data" set.
$ kubectl config set-cluster mgmt1 --server=https://312E3E9D26B6C190DFDFD12511D30179.gr7.eu-north-1.eks.amazonaws.com
Cluster "mgmt1" set.
$ [...]
$ kubectl config set-context mgmt-test --user=platon-paas-user --cluster=mgmt-test
Context "mgmt-test" modified.
$ kubectl config use-context paas2
Switched to context "paas2".

After you have configured kubectl you can run kubectl version to verify that you can connect to the Platon PaaS cluster:

$ kubectl version
platon-kubectl-auth: Starting authentication: https://console.paas.sikt.no/oidc/authorization?[...]
platon-kubectl-auth: Login completed
Client Version: v1.30.0
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
Server Version: v1.31.11-eks-ace6451

If you can see a "Server Version" line in the output, kubectl was able to connect to the cluster.

Locating your project in Kubernetes

Each GitLab project gets its own namespace in Kubernetes. To examine the project, you must locate the namespace identifier.

You can view your namespace in the Platon PaaS console. Search for your project at that page and click it to get details. There you should see a line specifying the namespace. E.g.:

Kubernetes Namespace: platon-kurs-username-website

In this case, platon-kurs-username-website is the namespace. You provide the namespace to kubectl with the -n option. E.g.:

$ kubectl -n platon-kurs-username-website get all
NAME                            READY   STATUS    RESTARTS   AGE
pod/production-dfb888cd-h85nx   1/1     Running   0          30m
pod/production-dfb888cd-r4jsv   1/1     Running   0          30m
pod/staging-9f6f6bf54-whlzh     1/1     Running   0          87m

NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
service/production   ClusterIP   172.16.253.58   <none>        80/TCP    30m
service/staging      ClusterIP   172.16.56.15    <none>        80/TCP    87m

NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/production   2/2     2            2           30m
deployment.apps/staging      1/1     1            1           87m

NAME                                  DESIRED   CURRENT   READY   AGE
replicaset.apps/production-dfb888cd   2         2         2       30m
replicaset.apps/staging-9f6f6bf54     1         1         1       87m

note

Here you used kubectl get all to show multiple resources in your project. Despite being named all, this is just a subset of the resources in your project. In particular, there are secrets (that cannot be listed) and ingresses (that are not listed by default).

To view specific resources, you should specify the resource you are interested in. For example, to view ingresses:

$ kubectl -n platon-kurs-username-website get ingresses
NAME         HOSTS                                       ADDRESS         PORTS     AGE
production   username-website.paas2.uninett.no           172.16.130.93   80, 443   33m
staging      username-website-staging.paas2.uninett.no   172.16.130.93   80, 443   90m

Examining resources

There are two main commands to examine resources:

• kubectl get [type]: List resources of [type].

• kubectl describe [type] [name]: Show detailed information about a particular resource.

For example, you can list all deployments using kubectl get deployments:

$ kubectl -n platon-kurs-username-website get deployments
NAME         READY   UP-TO-DATE   AVAILABLE   AGE
production   2/2     2            2           37m
staging      1/1     1            1           94m

And examine a particular deployemnt using kubectl describe deployment:

$ kubectl -n platon-kurs-username-website describe deployment production
Name:                   production
Namespace:              platon-kurs-username-website
[...]

You can also dump the raw resource in YAML-format using kubectl get [type] [name] -o yaml:

$ kubectl -n platon-kurs-username-website get deployment production -o yaml
apiVersion: apps/v1
kind: Deployment
metadata:
[...]

Resource types

There are many resource types available in Kubernetes. The two that are most useful to look at are:

• deployment: A deployment tells Kubernetes to run a set of container images.
• pod: A pod is responsible for running the actual container images. It consists of one or more containers.

Viewing logs

You can view the logs of your containers using the kubectl logs-command. To view the logs you must specify the name of a pod, which you can get using kubectl get pods. You can then get the logs from the pod using kubectl logs [pod]:

$ kubectl -n platon-kurs-username-website get pods
NAME                        READY   STATUS    RESTARTS   AGE
production-dfb888cd-h85nx   1/1     Running   0          45m
production-dfb888cd-r4jsv   1/1     Running   0          45m
staging-9f6f6bf54-whlzh     1/1     Running   0          102m
§
$ kubectl -n platon-kurs-username-website logs production-dfb888cd-h85nx | head
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
[...]