Access a Konvoy cluster

Using the operations portal

When Konvoy completes cluster provisioning, it provides details for where to acces the cluster’s operations portal.

Kubernetes cluster and addons deployed successfully!

Run `konvoy apply kubeconfig` to update kubectl credentials.

Run `konvoy check` to verify that the cluster has reached a steady state and all deployments have finished.

Navigate to the URL below to access various services running in the cluster.
  https://lb_addr-12345.us-west-2.elb.amazonaws.com/ops/landing
And login using the credentials below.
  Username: AUTO_GENERATED_USERNAME
  Password: SOME_AUTO_GENERATED_PASSWORD_12345

If the cluster was recently created, the dashboard and services may take a few minutes to be accessible.

If you have an administrative admin.conf KUBECONFIG file, you can retrieve the URL after the cluster deploys, using the following command:

konvoy get ops-portal

The URL offers access to the operations portal. This is a web UI that links to various dashboards of the tooling integrated on Konvoy Kubernetes clusters. A web application within the cluster hosts this UI and runs on the cluster’s ingress load balancer.

To access the UI:

Enter the URL in your browser.
Select the “Launch Console” button.
Enter your username and password and select “Login”.

You are taken to the Konvoy operations portal. The portal provides an overview of cluster status, and shortcuts to several dashboards to addon services, such as Grafana.

IMPORTANT: When using an automated provisioner, do not delete the load balancer created by the cloud provider for the traefik service.
If the load balancer is deleted, follow the steps below to regain access to the ops-portal. To complete the instructions below, you must update your kubectl credentials with the admin.conf file, created for your Konvoy cluster, by running the ./konvoy apply kubeconfig command. More on that here.

Recreate the Service resource for traefik-kubeaddons in the kubeaddons namespace.
```
kubectl get service -n kubeaddons traefik-kubeaddons -o json | jq 'del(.status)' | kubectl apply -f -
```
If you do not have jq, save the output of kubectl get service to a file, remove the status: value, and kubectl apply -f the file.
Delete the traefik pods and let Kubernetes recreate them, this causes other pods to restart with the new configuration.
```
kubectl delete pods -n kubeaddons -l release=traefik-kubeaddons
```
Retrieve the new address.
```
konvoy get ops-portal
```

Using kubectl

One of the most common ways to perform administrative tasks and interact with a Kubernetes cluster is through the kubectl command line interface. With kubectl, you can run commands against native Kubernetes clusters to retrieve information about key cluster activities and to control specific cluster-level components and operations.

Use kubectl to:

Deploy applications
Manage cluster resources
View logs and status messages

For a complete list of kubectl operations, see overview of kubectl.

Install kubectl

The specific steps required for installing kubectl depend on your operating system platform. For platform-specific install instructions, see the Kubernetes installation and setup information for your platform.

Configure kubectl (for cluster administrators)

The kubectl program uses information in its configuration file to customize operations for a specific cluster. By default, the configuration file for kubectl is config and is located in the $HOME/.kube directory. You can specify other kubeconfig files by setting the KUBECONFIG environment variable or by setting the --kubeconfig flag.

After you create a cluster with the konvoy up command, the simplest way to add that cluster’s kubectl configuration to either the default ~/.kube/config file, or the file specified using the KUBECONFIG environment variable, is to run the following konvoy command:

konvoy apply kubeconfig

This command applies the contents of the local Konvoy admin.conf configuration file to your existing default configuration.

Configure kubectl (for authorized users)

This section shows how non-administrative users can access the cluster’s API, using kubectl with credentials derived from their third-party single sign-on environment.

Enter the URL of the operations portal in your browser, as noted in Using the operations portal.
Select the Generate kubectl token button.
Select the appropriate Kubernetes cluster authenticator (usually shown as Kubernetes cluster).
Log in using your username and password, or using a third-party integrated sign-on.
Follow instructions and execute commands in your terminal, as directed on the page.

NOTE: By default, new users who log in this way will not have permissions on the cluster's API.

Your cluster administrator must grant you permissions on the cluster, using a Kubernetes role-binding.

An unprivileged user will receive errors like the following through kubectl:

Error from server (Forbidden): nodes is forbidden: User "${USERNAME}" cannot list resource "nodes" in API group "" at the cluster scope

For example, if your user needs administrative permissions, the following command grants them full cluster administration:

kubectl create clusterrolebinding rb_admin_${USERNAME} --clusterrole=cluster-admin --user=${USERNAME}

Create an administrative service account

While service accounts typically provide API access to applications running on the cluster, they can also provide access to users or services outside of the cluster. A service account does not require credentials derived from a third-party single sign-on environment. A cluster administrator must be able to access the cluster even when a third-party single sign-on environment is unavailable. This makes the service account a good choice for sharing administrative access.

To create an administrative service account, configure kubectl for a cluster administrator. Then, run the following command:

konvoy generate cluster-admin-serviceaccount ${SERVICEACCOUNT_NAME} | kubectl apply -f-

To use the service account to access the API, view the kubeconfig for the service account, then give the kubeconfig to a user or application.

konvoy view serviceaccount-kubeconfig --namespace kube-system ${SERVICEACCOUNT_NAME}

Common kubectl command examples

The following section list several important commands relevant for working with Konvoy clusters. For information about other commands, see the kubectl cheatsheet.

View addons and system pods

Konvoy clusters come with a series of addons deployed. These addons exist in one of three namespaces:

kube-system: Core Kubernetes components, and a limited set of addons that require administrative access to the cluster deploy here
velero: Velero (used for cluster backup and restore) and its components are deployed here
kubeaddons: Most addons are deployed here unless otherwise specified

For a basic status check of all the addon and system-related pods, run the following commands:

kubectl -n kube-system get pods
kubectl -n velero get pods
kubectl -n kubeaddons get pods