Skip to main content

Install on Kubernetes using Helm

If you don't have a Kubernetes cluster, follow the MicroK8S guide for the easiest deployment scenario.

Prerequisites​

  1. Make sure you read the Identity management section to undestand the need of an OpenID provider (IdP).
    By default, this chart will install Keycloak as an OpenID provider for the user authentication.
  2. Have a functional Kubernetes cluster with
  3. Configure a domain where to install Osie
    • cloud.<your-domain>.<tld> configured in your DNS pointing to your ingress IP
    • an auth.<your-domain>.<tld> subdomain for Keycloak, if you don't already have an identity provider (IdP).
  4. Helm installed on your local machine.

Add the Helm repository​

helm repo add osie https://helm.osie.io
helm repo update

Configure the values.yaml file​

For the complete list of configurable variables, check the values.yaml file of the Chart.

Example 1: With Keycloak included​

This configuration installs Keycloak as well using the Keycloak chart from Bitnami.

values.yaml
global:
  ingress:
    enabled: true
    hostname: "cloud.example.com"
    ingressClassName: "nginx"
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt
      # Required by Keycloak when using Nginx ingress
      nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
    tls: true
keycloak:
  ingress:
    hostname: auth.example.com
smtp:
  password: # smtp password 
  user: # smtp user 
  starttls: true
  auth: true
  port: 587
  host: # smtp server 
  from: [email protected]
  fromDisplayName: My Cloud Company

Example 2: Without Keycloak​

If you have deployed your own identity provider, you have to manually specify the Oauth2 / OpenID configuration.

values.yaml
global:
  ingress:
    enabled: true
    hostname: "cloud.example.com"
    ingressClassName: "nginx"
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt
    tls: true
# OpenID configuration for the Osie client portal
ui:
  oauth2:
    clientId: client-id
    issuerUri: https://auth.example.com/path/to/openid
# (Optional) if you use different OpenID for the Administrators
# otherwise the ones from the client portal will be used
admin:
  oauth2:
    clientId: admin-client-id
    issuerUri: https://auth.example.com/path/to/openid   

keycloak:
  enabled: false
smtp:
  ...

High Availability​

If you have a highly available Kubernetes cluster (having 3+ nodes), then you can deploy the databases and the services with replication and high availability. Below is an example of how the replicaCount and architecture can be adjusted.

values.yaml
ui:
 replicaCount: 3
admin:
 replicaCount: 3
api:
 replicaCount: 3 
keycloak:
  replicaCount: 3
  postgresql:
    architecture: replication
mongodb:
   architecture: replicaset
   replicaCount: 3
redis:
   architecture: replication

Install using the chart​

By using the created values.yaml file you can proceed with the installation.

helm --namespace osie upgrade --install --create-namespace osie osie/osie -f values.yaml

Check the Kubernetes pods in the namespace.

$ kubectl -n osie get pods

osie-admin-5dc5b4ff59-hbzmz     1/1     Running   0          22h
osie-api-0                      1/1     Running   0          22h
osie-keycloak-0                 1/1     Running   0          28h
osie-mongodb-5fc58bbc78-mc6xw   1/1     Running   0          28h
osie-postgresql-0               1/1     Running   0          28h
osie-rabbitmq-0                 1/1     Running   0          28h
osie-redis-master-0             1/1     Running   0          28h
osie-ui-566c759d8-srskk         1/1     Running   0          22h

Check the ingress hostnames.

$ kubectl -n osie get ingress

osie-admin      nginx   cloud.example.com        12.34.56.78   80, 443   28h
osie-api        nginx   cloud.example.com        12.34.56.78   80, 443   28h
osie-keycloak   nginx   cloud.example.com        12.34.56.78   80, 443   28h
osie-ui         nginx   cloud.example.com        12.34.56.78   80, 443   28h

Post installation​

Now Osie is installed on your Kubernetes cluster and ready to be used. Here are some steps to be performed.

Save the bcrypt password​

Osie encrypts some sensitive information that's stored in the database, such as passwords and access keys.
It uses a bcrypt symmetric key that's being configured as an environment variable (OSIE_ENCRYPTION_DEFAULT_KEY).
Since the encryption is symmetric the same key must be used to decrypt the data, therefore is very important the key is not lost, otherwise some data from the database can't be decrypted.
The helm chart generates a random bcrypt password key that's saved inside the <release-name>-bcrypt secret.
It's recommended to save the key somewhere externally as well, so that you can reuse it in the event of a disaster recovery.

# Retrieve the bcrypt password and save it somewhere externally
kubectl -n osie get secret osie-bcrypt -o json | jq -r '.data."bcrypt-password"' | base64 -d

Log in to Osie Admin panel​

The admin panel should be acessible at https://cloud.example.com/osie_admin.

The default admin username is osie_admin.

Retrieve the admin password from Kubernetes secret​

If you have jq installed simply run

kubectl -n osie get secret osie-keycloak -o json | jq -r '.data."admin-password"' | base64 -d

Otherwise retrieve the secret and base64 decode the data.admin-password key.

kubectl -n osie get secret osie-keycloak -o yaml

Upgrading or reconfiguring​

You can use the helm upgrade command to upgrade to newer versions of Osie or to restart the components if you make changes to the values.yaml.
If you used the chart to install Keycloak as well, it is recommended to prevent the keycloakConfigCli running again, since that's only needed during the first installation

values.yaml
# Disable keycloakConfigCli to run again
keycloak:
  keycloakConfigCli:
    enabled: false
# First update the helm repository to get the latest chart version
helm repo update
# Run the helm upgrade command
helm --namespace osie upgrade osie osie/osie -f values.yaml

Automated Backups​

Configure automated backups with Velero

Next steps​