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. Have a functional Kubernetes cluster with
  2. Configure a domain where to install Osie
    • osie.<your-domain>.<tld> configured in your DNS pointing to your ingress IP
  3. 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: Default (Built-in Login)​

This is the simplest configuration. Osie uses its built-in identity provider for user authentication — no external IdP is required.

values.yaml
global:
  ingress:
    enabled: true
    hostname: "osie.mycompany.com"
    ingressClassName: "nginx"
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt
    tls: true
keycloak:
  enabled: false
Looking for Single Sign-On?

If you want to use Keycloak or an external OpenID Connect provider for federated authentication, see the Single Sign-On (SSO) guide.

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
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-mongodb-5fc58bbc78-mc6xw   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   osie.mycompany.com       12.34.56.78   80, 443   28h
osie-api        nginx   osie.mycompany.com       12.34.56.78   80, 443   28h
osie-ui         nginx   osie.mycompany.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 accessible at https://osie.mycompany.com/osie_admin.

On first access, you will be guided through an onboarding process where you can create your administrator account and set a password.

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.

# 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​