Version: next

Deploying Using Helm

Stratos is an Open Source Web-based Management console for Cloud Foundry. It allows users and administrators to both manage applications running in the Cloud Foundry cluster and perform cluster management tasks.

Installation

Stratos can be installed to a Kubernetes cluster using Helm. Either Helm 2 or Helm 3 can be used, although we recommend using the newer Helm 3 version.

Ensure the Helm client and kubectl CLIs are installed. If you are using Helm 2, ensure you've initialized Tiller into your cluster with the appropriate Service Account.

The Helm chart is published to the Stratos Helm repository.

You will need to have the Stratos Helm repository added to your Helm setup, if you do not, run:

helm repo add stratos https://cloudfoundry.github.io/stratos

Check the repository was successfully added by searching for the console, for example:

helm search repo console
NAME CHART VERSION APP VERSION DESCRIPTION
stratos/console 4.3.0 4.3.0 A Helm chart for deploying Stratos UI Console

Note: Version numbers will depend on the version of Stratos available from the Helm repository

Note: Commands shown in this document are for Helm version 3. For Helm version 2, when installing, instead of supplying the name via the --name flag, it is supplied as the first argument, before the chart name.

To install Stratos:

kubectl create namespace console
helm install my-console stratos/console --namespace=console

Note: The first kubectl command will create a namespace for Stratos. With Helm 3 you must create a namespace before installing. We recommend installing Stratos into a separate namespace.

Note: This assumes that a storage class exists in the Kubernetes cluster that has been marked as default. If no such storage class exists, a specific storage class needs to be specified, please see the following section Specifying a custom Storage Class.

You can change the namespace (--namespace) and the release name to values of your choice.

This will create a Stratos instance named my-console in a namespace called console in your Kubernetes cluster.

After the install, you should be able to access the Console in a web browser by following the instructions below.

Advanced installation topics are covered in the the Advanced Topics section below.

Helm Chart Configuration

The following table lists the configurable parameters of the Stratos Helm chart and their default values.

ParameterDescriptionDefault
imagePullPolicyImage pull policyIfNotPresent
console.sessionStoreSecretSecret to use when encrypting session tokensauto-generated random value
console.ssoLoginWhether to enable SSO Login and use the UAA Login UI instead of the built-in onefalse
console.ssoOptionsAdvanced options to customize the SSO experience
console.ssoAllowListList of permitted redirect URLs for SSO authentication
console.backendLogLevelLog level for backend (info, debug)info
console.service.externalIPsExternal IPs to add to the console service[]
console.service.loadBalancerIPIP address to assign to the load balancer for the metrics service (if supported)
console.service.loadBalancerSourceRangesList of IP CIDRs allowed access to load balancer (if supported)[]
console.service.typeService type for the console (ClusterIP, NodePort, LoadBalancer, ExternalName etc)ClusterIP
console.service.servicePortService port for the console service443
console.service.externalNameExternal name for the console service when service type is ExternalName
console.service.nodePortNode port to use for the console service when service type is NodePort or LoadBalancer
console.service.ingress.enabledEnable ingress for the console servicefalse
console.service.ingress.hostHost for the ingress resource
console.service.ingress.secretNameName of an existing secret containing the TLS certificate for ingress
console.service.http.enabledEnabled HTTP access to the console service (as well as HTTPS)false
console.service.http.servicePortService port for HTTP access to the console service when enabled80
console.service.http.nodePortNode port for HTTP access to the console service (as well as HTTPS)
console.templatesConfigMapNameName of config map that provides the template files for user invitation emails
console.userInviteSubjectEmail subject of the user invitation message
console.techPreviewEnable/disable Tech Preview featuresfalse
console.apiKeysEnabledEnable/disable API key-based access to Stratos API (disabled, admin_only, all_users)admin_only
console.ui.listMaxSizeOverride the default maximum number of entities that a configured list can fetch. When a list meets this amount additional pages are not fetched
console.ui.listAllowLoadMaxedIf the maximum list size is met give the user the option to fetch all resultsfalse
console.localAdminPasswordUse local admin user instead of UAA - set to a password to enable
console.tlsSecretNameSecret containing TLS certificate to use for the Console
console.mariadb.externalUse an external database instead of the built-in MariaDBfalse
console.mariadb.databaseName of the database to useconsole
console.mariadb.userName of the user for accessing the databaseconsole
console.mariadb.userPasswordPassword of the user for accessing the database. Leave blank for the built-in database to generate a random password
console.mariadb.rootPasswordPassword of the root user for accessing the database. Leave blank for the built-in database to generate a random password
console.mariadb.hostHostname of the database when using an external db
console.mariadb.portPort of the database when using an external db3306
console.mariadb.tlsTLS mode when connecting to database (true, false, skip-verify, preferred)false
console.artifactHubDisabledDisable the Helm Artifact Hub Endpointfalse
uaa.endpointURL of the UAA endpoint to authenticate with
uaa.consoleClientClient to use when authenticating with the UAAcf
uaa.consoleClientSecretClient secret to use when authenticating with the UAA
uaa.consoleAdminIdentifierScope that identifies an admin user of Stratos (e.g. cloud_controller.admin
uaa.skipSSLValidationSkip SSL validation when when authenticating with the UAAfalse
env.SMTP_AUTHAuthenticate against the SMTP server using AUTH command when Sending User Invite emailsfalse
env.SMTP_FROM_ADDRESSFrom email address to use when Sending User Invite emails
env.SMTP_USERUser name to use for authentication when Sending User Invite emails
env.SMTP_PASSWORDPassword to use for authentication when Sending User Invite emails
env.SMTP_HOSTServer host address to use for authentication when Sending User Invite emails
env.SMTP_PORTServer port to use for authentication when Sending User Invite emails
kube.authSet to "rbac" if the Kubernetes cluster supports Role-based access control"rbac"
kube.organizationRegistry organization to use when pulling images
kube.registry.hostnameHostname of registry to use when pulling imagesdocker.io
kube.registry.usernameUsername to use when pulling images from the registry
kube.registry.passwordPassword to use when pulling images from the registry
console.podAnnotationsAnnotations to be added to all pod resources
console.podExtraLabelsAdditional labels to be added to all pod resources
console.statefulSetAnnotationsAnnotations to be added to all statefulset resources
console.statefulSetExtraLabelsAdditional labels to be added to all statefulset resources
console.deploymentAnnotationsAnnotations to be added to all deployment resources
console.deploymentExtraLabelsAdditional labels to be added to all deployment resources
console.jobAnnotationsAnnotations to be added to all job resources
console.jobExtraLabelsAdditional labels to be added to all job resources
console.service.annotationsAnnotations to be added to all service resources
console.service.extraLabelsAdditional labels to be added to all service resources
console.service.ingress.annotationsAnnotations to be added to the ingress resource
console.service.ingress.extraLabelsAdditional labels to be added to the ingress resource
console.sslProtocolsSSL Protocols to use for the nginx configurationTLSv1.2 TLSv1.3
console.sslCiphersSSL Ciphers to use for the nginx configurationHIGH:!aNULL:!MD5
console.nodeSelectorNode selectors to use for the console Pod
mariadb.nodeSelectorNode selectors to use for the database Pod
configInit.nodeSelectorNode selectors to use for the configuration Pod
console.pspEnabledEnable Pod Security Policies. Set this to true if you cluster is configured with PSPs enabledfalse
console.pspNameName of an existing Pod Security Policy to use instead of the one created by the chart when PSPs are enabled
console.pspAnnotationsAnnotations to be added to all pod security policy resources
console.pspExtraLabelsAdditional labels to be added to all pod security policy resources

Accessing the Console

To check the status of the instance use the following command:

helm status my-console

Note: Replace my-console with the value you used for the name parameter, or if you did not provide one, use the helm list command to find the release name that was automatically generated for you.

The console is exposed via an HTTPS service - RELEASE-NAME-ui-ext (where RELEASE-NAME is the name used for the name parameter when installing). You can find the details of this service with:

kubectl get services -n NAMESPACE
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
my-console-mariadb ClusterIP 10.105.216.25 <none> 3306/TCP 60s
my-console-ui-ext NodePort 10.109.207.70 <none> 443:31067/TCP 60s

In this example, Stratos has been deployed withe the service configured as NodePort.

The URL you use for accessing Stratos will depend on the service configuration and the environment that you have used.

Note: If you did not provide a certificate when installing, Stratos will use a self-signed certificate, so you will see a certificate warning which you access Stratos in a browser.

Upgrading your deployment

To upgrade your instance when using the Helm repository, fetch any updates to the repository:

helm repo update

To update an instance, the following assumes your instance is called my-console:

helm upgrade my-console stratos/console

After the upgrade, perform a helm list to ensure your console is the latest version.

Uninstalling

To uninstall Stratos, delete the Helm release and also delete the Kubernetes namespace:

helm delete my-console --purge
kubectl delete namespace console

Note: Stratos creates secrets in the namespace as part of an initialization job. These are not managed by Helm, so make sure you delete the namespace to remove these secrets.

Advanced Topics

Using a Load Balancer

If your Kubernetes deployment supports automatic configuration of a load balancer (e.g. Google Container Engine), specify the parameters console.service.type=LoadBalancer when installing.

kubectl create namespace console
helm install my-console stratos/console --namespace=console --set console.service.type=LoadBalancer

Using an Ingress Controller

Bare minimum Stratos deployment with an Ingress

  1. Deploy ingress-nginx Ingress controller into your Kubernetes cluster using the Helm chart or Kubernetes spec files.
  2. Create values.yaml with the following Stratos Helm chart configuration values:
console:
service:
ingress:
enabled: true
  1. Install Stratos:
helm repo add stratos https://cloudfoundry.github.io/stratos
kubectl create namespace console
helm install my-console stratos/console --namespace=console --values values.yaml
  1. Obtain Ingress address by running kubectl get ingress --namespace=console, your Stratos installation should be accessible at that address.

Note that configuration above would result in a deployment with self-signed HTTPS certificates and Stratos service being a default backend for the Ingress. The following steps most likely would be required for a production deployment:

  1. Acquire a static IP address for the Ingress.
  2. Assign a domain name to the static IP via a DNS record and set console.service.ingress.host value.
  3. Create a Kubernetes secret containing valid HTTPS certificates for the domain and set console.service.ingress.secretName value.

Ingress configuration

If your Kubernetes Cluster supports Ingress, you can expose Stratos through Ingress by supplying the appropriate ingress configuration when installing.

This configuration is described below:

ParameterDescriptionDefault
console.service.ingress.enabledEnables ingressfalse
console.service.ingress.annotationsAnnotations to be added to the ingress resource.{}
console.service.ingress.extraLabelsAdditional labels to be added to the ingress resource.{}
console.service.ingress.hostThe host name that will be used for the Stratos service.
console.service.ingress.secretNameThe existing TLS secret that contains the certificate for ingress.

If console.service.ingress.host isn't provided, Stratos service will be used as the default backend.

By default a certificate will be generated for TLS. You can provide your own certificate by creating a secret and specifying this with console.service.ingress.secretName.

Note: If you do not supply console.service.ingress.host but do supply env.DOMAIN then the host console.[env.DOMAIN] will be used.

Deploying from a Private Image Repository

If the images used by the chart are hosted in a private repository, the following needs to be specified. Save the following to a file called private_overrides.yaml. Replace REGISTRY USER PASSSWORD, REGISTRY USERNAME, REGISTRY URL with the appropriate values. USER EMAIL can be left blank.

kube:
registry:
password: <REGISTRY USER PASSWORD>
username: <REGISTRY USERNAME>
hostname: <REGISTRY URL>
email: <USER EMAIL or leave blank>

Deploy with:

kubectl create namespace console
helm install my-console stratos/console --namespace=console -f private_overrides.yaml

Deploying with your own TLS certificates

By default the console will generate self-signed certificates for demo purposes. To configure Stratos to use your provided TLS certificate, create a TLS secret in the namespace you are installing into and specify this secret name using the helm chart value console.tlsSecretName when installing.

Assuming you have your certificate and key in the files tls.crt and tls.key, create the secret with:

kubectl create secret tls -n NAMESPACE stratos-tls-secret --cert=tls.crt --key=tls.key

Where NAMESPACE is the namespace you are installing Stratos into - you will need to manually create the namespace first if it does not already exist.

You can now install Stratos with:

kubectl create namespace console
helm install my-console stratos/console --namespace=console --set console.tlsSecretName=stratos-tls-secret

Using an External Database

You can choose to use Stratos with an external database, rather than deploying a single-node MariaDB instance as part of the Helm install.

To do so, specify console.mariabdb.external=true when deploying.

You will also need to specify:

  • console.mariadb.host as the hostname of the external MariaDB database server
  • console.mariadb.port as the port of the external MariaDB database server (defaults to 3306)
  • console.mariadb.tls as the TLS mode (default is false, use true for a TLS connection to the database server)
  • console.mariadb.database as the name of the database
  • console.mariadb.user as the username to connect to the database server
  • console.mariadb.userPassword as the password to connect to the database server

When using an external database server, Stratos expects that you have:

  • Created a user that will be used to access the database
  • Created a database for the Stratos tables and data
  • Granted appropriate permissions so that the user can access the database

Note: When using a database from a Cloud provider, ensure that the username is correct - in some cases this will be username@servername - check the provided connection documentation

Specifying UAA configuration

When deploying with SCF, the scf-config-values.yaml (see SCF Wiki link) can be supplied when installing Stratos.

kubectl create namespace console
helm install my-console stratos/console --namespace=console -f scf-config-values.yaml

UAA configuration can be specified by providing the following configuration.

Create a yaml file with the content below and and update according to your environment and save to a file called uaa-config.yaml.

uaa:
endpoint: https://uaa.cf-dev.io:2793
consoleClient: cf
consoleClientSecret:
consoleAdminIdentifier: cloud_controller.admin
skipSSLValidation: false

To install Stratos with the above specified configuration:

kubectl create namespace console
helm install my-console stratos/console --namespace=console -f uaa-config.yaml

Configuring a local user account

This allows for deployment without a UAA. To enable the local user account, supply a password for the local user in the deployment command, as follows. All other steps for each deployment method should be followed as in the preceding sections above.

To deploy using our Helm repository:

kubectl create namespace console
helm install my-console stratos/console --namespace=console --set console.localAdminPassword=<password>

Specifying Annotations and Labels

In some scenarios it is useful to be able to add custom annotations and/or labels to the Kubernetes resources that the Stratos Helm chart creates.

The Stratos Helm chart exposes a number of Helm chart values that can be specified in order to do this - they are:

ParameterDescriptionDefault
console.podAnnotationsAnnotations to be added to all pod resources
console.podExtraLabelsAdditional labels to be added to all pod resources
console.statefulSetAnnotationsAnnotations to be added to all statefulset resources
console.statefulSetExtraLabelsAdditional labels to be added to all statefulset resources
console.deploymentAnnotationsAnnotations to be added to all deployment resources
console.deploymentExtraLabelsAdditional labels to be added to all deployment resources
console.jobAnnotationsAnnotations to be added to all job resources
console.jobExtraLabelsAdditional labels to be added to all job resources
console.service.annotationsAnnotations to be added to all service resources
console.service.extraLabelsAdditional labels to be added to all service resources
console.service.ingress.annotationsAnnotations to be added to the ingress resource
console.service.ingress.extraLabelsAdditional labels to be added to the ingress resource

Requirements

Storage Class

Stratos uses persistent volumes. In order to deploy it in your Kubernetes environment, you must have a storage class available.

Without configuration, the Stratos Helm Chart will use the default storage class. If a default storage class is not available, installation will fail.

To check if a default storage class exists, you can list your configured storage classes with kubectl get storageclass. If no storage class has (default) after it, then you need to either specify a storage class override or declare a default storage class for your Kubernetes cluster.

For non-production environments, you may want to use the hostpath storage class. See the SCF instructions for details on setting this up. Note that you will need to make this storage class the default storage class, e.g.

kubectl patch storageclass <your-class-name> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Where <your-class-name> would be hostpath if you follow the SCF instructions.

Specifying a custom Storage Class

If no default storage class has been defined in the Kubernetes cluster. The Stratos helm chart will fail to deploy successfully. To check if a default storage class exists, you can list your configured storage classes with kubectl. If no storage class has (default) after it, then you need to either specify a storage class override or declare a default storage class for your Kubernetes cluster.

Providing Storage Class override

kubectl get storageclass
NAME TYPE
ssd kubernetes.io/host-path
persistent kubernetes.io/host-path

For instance to use the storage class persistent to deploy Console persistent volume claims, store the following to a file called override.yaml.

---
storageClass: persistent

If you want MariaDB to use a specific storage class (which can be different to that used for the other components), then specify the following:

---
storageClass: persistent
mariadb:
persistence:
storageClass: persistent

Run Helm with the override:

kubectl create namespace console
helm install my-console stratos/console --namespace=console -f override.yaml

Create a default Storage Class

Alternatively, you can configure a storage class with storageclass.kubernetes.io/is-default-class set to true. For instance the following storage class will be declared as the default. If you don't have the hostpath provisioner available in your local cluster, please follow the instructions on link, to deploy one.

If the hostpath provisioner is available, save the file to storageclass.yaml

---
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
name: default
annotations:
storageclass.kubernetes.io/is-default-class: "true"
provisioner: kubernetes.io/host-path # Or whatever the local hostpath provisioner is called

To create it in your kubernetes cluster, execute the following.

kubectl create -f storageclass.yaml

See Storage Class documentation for more information.