# Kubernetes install ## Before you start {% hint style="info" %} Extra notes for installing on: * **Kubernetes clusters with limited permissions**: Read the [required permissions](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/required_permissions). * **OpenShift**: Refer to the [OpenShift installation instructions](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/openshift_install). {% endhint %} Before you start the installation of StackState: * Check the [requirements](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/requirements) to make sure that your Kubernetes environment fits the setup that you will use (recommended, minimal or non- high availability). * Check that you have the [required permissions](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/required_permissions). * Request access credentials to pull the StackState Docker images from [StackState support](https://support.stackstate.com/). * Add the StackState helm repository to the local helm client: ``` helm repo add stackstate https://helm.stackstate.io helm repo update ``` ## Install StackState {% hint style="info" %} For environments without internet access, also known as air-gapped environments, first follow [these extra instructions](https://archivedocs.stackstate.com/self-hosted-setup/no_internet/stackstate_installation). Also make sure to follow the air-gapped instalaltion instructions whenever those are present for a step. {% endhint %} 1. [Create the namespace where StackState will be installed](#create-namespace) 2. [Generate the `values.yaml` file](#generate-values.yaml) 3. [Deploy StackState with Helm](#deploy-stackstate-with-helm) 4. [Access the StackState UI](#access-the-stackstate-ui) ### Create namespace Start by creating the namespace where you want to install StackState and deploy the secret in that namespace. In our walkthrough we will use the namespace `stackstate`: ``` kubectl create namespace stackstate ``` ### Generate `values.yaml` The `values.yaml` file is required to deploy StackState with Helm. It contains your StackState license key, StackState Receiver API key and other important information. {% hint style="info" %} **Before you continue:** Make sure you have the latest version of the Helm charts with `helm repo update`. {% endhint %} The StackState `values.yaml` file can be generated by running a separate Helm Chart, the `stackstate/stackstate-values` chart. A sample command line is: ``` > helm template \ --set license='' \ --set baseUrl='' \ --set pullSecret.username='' \ --set pullSecret.password='' \ sts-values \ stackstate/stackstate-values > values.yaml ``` This command will generate a values.yaml file which contains the necessary configuration for installing the StackState Helm Chart. {% hint style="info" %} The StackState administrator passwords will be autogenerated by the above command and are output as comments in the generated `values.yaml` file. The actual values contain the `bcrypt` hashes of those passwords so that they're securely stored in the Helm release in the cluster. {% endhint %} The values that can be passed to this chart are: | Configuration | Value | Description | | ------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Receiver API Key | `receiverApiKey` | The API key used by StackState to receive data from agents. This is a secret key that should be kept private. If you omit this, a random key will be generated for you. | | Base URL | `baseUrl` | The ``. The external URL for StackState that users and agents will use to connect. For example `https://stackstate.internal`. If you haven't decided on an Ingress configuration yet, use `http://localhost:8080`. This can be updated later in the generated file. | | Username and password\*\* | `-u` `-p` | The username and password used by StackState to pull images from quay.io/stackstate repositories. For air-gapped environments these need to be the username and password for the local docker registry. | | License key | `license` | The StackState license key. | | Admin API password | `adminApiPassword` | The password for the admin API. Note that this API contains system maintenance functionality and should only be accessible by the maintainers of the StackState installation. If you omit this, a random password will be generated for you. If you do pass this value and it's not bcrypt hashed, the chart will hash it for you. | | Default password | `adminPassword` | The password for the default user (`admin`) to access StackState's UI. If you omit this, a random password will be generated for you. If you do pass this value and it's not bcrypt hashed, the chart will hash it for you. | | Image Registry | `imageRegistry` | The registry where the StackState images are hosted. If not provided, the default value will be 'quay.io' | | Pull Secret Username | `pullSecret.username` | The username used to pull images from the Docker registry where the StackState images are hosted. | | Pull Secret Password | `pullSecret.password` | The password used to pull images from the Docker registry where the StackState images are hosted. | {% hint style="info" %} Store the generated `values.yaml` file somewhere safe. You can reuse this file for upgrades, which will save time and (more importantly) will ensure that StackState continues to use the same API key. This is desirable as it means Agents and other data providers for StackState won't need to be updated. {% endhint %} ### Deploy StackState with Helm The recommended deployment of StackState is a production ready, high availability setup with many services running redundantly. If required, it's also possible to run StackState in a non-redundant setup, where each service has only a single replica. This setup is only recommended for a test environment. For air-gapped environments follow the instructions for the air-gapped installations. {% tabs %} {% tab title="High availability setup" %} To deploy StackState in a high availability setup on Kubernetes: 1. Before you deploy: * [Create the namespace where StackState will be installed](#create-namespace) * [Generate `values.yaml`](#generate-values.yaml) 2. **(Optionally)** [Create a `small_values.yaml`](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/small_profile_setup) if you want to deploy a small profile setup. Add the `--values small_values.yaml` flag to the command below. 3. Deploy the latest StackState version to the `stackstate` namespace with the following command: ``` helm upgrade \ --install \ --namespace stackstate \ --values values.yaml \ stackstate \ stackstate/stackstate-k8s ``` {% endtab %} {% tab title="Non-high availability setup" %} To deploy StackState in a non-high availability setup on Kubernetes: 1. Before you deploy: * [Create the namespace where StackState will be installed](#create-namespace) * [Generate `values.yaml`](#generate-values.yaml) * [Create `nonha_values.yaml`](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/non_high_availability_setup) 2. Deploy the latest StackState version to the `stackstate` namespace with the following command: ```bash helm upgrade \ --install \ --namespace stackstate \ --values values.yaml \ --values nonha_values.yaml \ stackstate \ stackstate/stackstate-k8s ``` {% endtab %} {% tab title="Air-gapped, high availability setup" %} To deploy StackState in a air-gapped, high availability setup on Kubernetes: 1. Before you deploy: * [Follow these extra instructions for air-gapped installations](https://archivedocs.stackstate.com/self-hosted-setup/no_internet/stackstate_installation). * [Create the namespace where StackState will be installed](#create-namespace) * [Generate `values.yaml`](#generate-values.yaml) 2. **(Optionally)** [Create a `small_values.yaml`](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/small_profile_setup) if you want to deploy a small profile setup. Add the `--values small_values.yaml` flag to the command below. 3. Deploy the latest StackState version to the `stackstate` namespace with the following command: {% hint style="info" %} If you've created a `small_values.yaml` file, add `--values small_values.yaml` to the command below. {% endhint %} ``` helm upgrade \ --install \ --namespace stackstate \ --values local-docker-registry.yaml \ --values values.yaml \ stackstate \ stackstate/stackstate-k8s ``` {% endtab %} {% tab title="Air-gapped, non-high availability setup" %} To deploy StackState in a air-gapped, non-high availability setup on Kubernetes: 1. Before you deploy: * [Follow these extra instructions for air-gapped installations](https://archivedocs.stackstate.com/self-hosted-setup/no_internet/stackstate_installation). * [Create the namespace where StackState will be installed](#create-namespace) * [Generate `values.yaml`](#generate-values.yaml) * [Create `nonha_values.yaml`](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/non_high_availability_setup) 2. Deploy the latest StackState version to the `stackstate` namespace with the following command: ```bash helm upgrade \ --install \ --namespace stackstate \ --values local-docker-registry.yaml \ --values values.yaml \ --values nonha_values.yaml \ stackstate \ stackstate/stackstate-k8s ``` {% endtab %} {% endtabs %} After the install, the StackState release should be listed in the StackState namespace and all pods should be running: ``` # Check the release is listed helm list --namespace stackstate # Check pods are running # It may take some time for all pods to be installed or available kubectl get pods --namespace stackstate ``` ### Access the StackState UI After StackState has been deployed you can check if all pods are up and running: ``` kubectl get pods --namespace stackstate ``` When all pods are up, you can enable a port-forward: ``` kubectl port-forward service/-stackstate-k8s-router 8080:8080 --namespace stackstate ``` StackState will now be available in your browser at `https://localhost:8080`. Log in with the username `admin` and the default password provided in the `values.yaml` file. Next steps are * [Expose StackState outside of the cluster](https://archivedocs.stackstate.com/self-hosted-setup/install-stackstate/kubernetes_openshift/ingress) * [Start monitoring your Kubernetes clusters](https://archivedocs.stackstate.com/get-started/k8s-quick-start-guide) * Give your [co-workers access](https://archivedocs.stackstate.com/self-hosted-setup/security/authentication).