Normally, our distribution platform Replicated uses KOTS to manage deployments and updates in self-hosted clusters. If you’d prefer to avoid using KOTS, you can alternatively manage deployments yourself using Helm. This will require more work to configure Opal correctly, but will allow greater control over the resources you deploy.

Initial Setup

To start, make sure you finish the Infrastructure Setup sections in the AWS Setup Guide or GKE Setup Guide.

Next, you’ll need to access Replicated's customer-facing download portal. This lists the available versions of Opal, and has instructions and credentials for Helm installs. Opal support will provide you with access to this download portal.

From here, you can either

Pull images directly from Opal’s registry OR
Use a private Docker registry

We recommend using Opal’s registry unless you have specific security concerns that require you to use a private registry.

Pull images from Opal’s Registry

Copy the license ID from step 1 in the download portal:
```
export LICENSE_ID=<license id>
```

# check the instructions in the download portal for the email to use here
helm registry login registry.replicated.com --username <email> --password $LICENSE_ID

Continue with the following Configure and Install via Helm steps.

Use a private Docker registry

Create the following repositories in your private registry:

fluent-bit
minio
opal-migrate
opal-ml
opal-web_backend
redis
redis-sentinel

Proceed with all of the steps from the Replicated download portal. When you reach steps 6 and 7 to download and edit values.yaml, continue with the following Configure and Install via Helm steps.

Configure and Install via Helm

Refer to the following annotated values.yaml file when you’re ready to configure your values for the Opal chart. Take note of the comments, and fill in anything with <angle brackets>.

env:
  # These are required for your environment to function correctly, and for us to push feature flags to you
  environment: on_prem
  onPremCustomerName: <the `customerName` from your license file>

  # Leave these values as-is
  ginMode: "release"
  authProvider: AUTH0
  authAudience: https://opal.dev
  redisHost: opal-web-redis-master
  redisPort: 6379

  # This will forward logs from your instance of Opal to us, making it easier for us to debug issues.
  # Set this to "false" if you'd like to disable log forwarding.
  # Either way, ensure it's a string, not a raw boolean
  enableRemoteLogging: "true"
  
  # Fill these in appropriately for the db instance you set up
  postgresUser: postgres
  postgresPassword: <postgres db password>
  postgresDb: opal
  postgresHost: <postgres host>
  postgresSslMode: "require"
  postgresPort: 5432

  # Generate secret values for these, and save them somewhere secure.
  authTokenEncryptionKey: <a random, secure string>
  csrfAuthenticationKey: <a random, secure string>
  databaseEncryptionKey:  <a random, secure string>
  opalApiEncryptionKey:  <a random, secure string>
  secureCookieHashkey: <a random, secure string>
  minioAccessKey: <a random, secure string>
  minioSecretKey: <a random, secure string>
  minioRootUser:  <a random, secure string>
  minioRootPassword:  <a random, secure string>

  # A DNS name you own that you will use to access Opal.
  hostname: <hostname for accessing opal>

  # Optional. Set this to have pods use an existing service account in your cluster. Otherwise, omit this.
  serviceAccount: <existing service account name>

  # This configures an SMTP provider for your instance of Opal to use for sending email notifications
  # If set to false, Opal uses its default external service for sending emails
  smtpEnable: true
  smtpServer: <smtp server>
  smtpPort: <smtp port>
  # You may also enable authentication for your customer SMTP server by setting this to true
  # If you do this, set the username + password below, and make sure smtpPort is set to 465
  smtpAuthEnable: false
  smtpUsername: <username for your SMTP server>
  smtpPassword: <password for your SMTP server>

image:
  # Leave these two as-is to use Opal's image registry directly
  repository: proxy.replicated.com/proxy/opal-onprem/179751979675.dkr.ecr.us-east-2.amazonaws.com
  useReplicatedPullSecret: true
  # If using a private helm registry, use the following instead:
  # repository: <your private registry's hostname>
  # useReplicatedPullSecret: false

# Setting `enabled` to true will deploy an Ingress resource you can use to route traffic to Opal
# If you disable this, you will need to create your own ingress that routes traffic to the `opal-web` service
ingress:
  enabled: true
  # Always leave `override=true`
  override: true
  overrideAnnotations:
    # Here, you should fill in annotations that will link your ingress to the load balancer you created in your cloud provider
    
    # For AWS, this will look something like:
    # kubernetes.io/ingress.class: alb
    # alb.ingress.kubernetes.io/scheme: internet-facing
    # alb.ingress.kubernetes.io/certificate-arn: <ACM certificate ARN>

    # For GCP, this will look something like
    # ingress.gcp.kubernetes.io/pre-shared-cert: opal-replicated
    # kubernetes.io/ingress.global-static-ip-name: opal-replicated

# If you need to turn off log-forwarding, set `enabled` to false here, and omit the other fields.
log-forwarder:
  enabled: true
  customer: <the `customerName` from your license file>

# Leave the rest of these as-is

database:
  migrationDirection: up
  dataSeedDirection: up

vault:
  enabled: false

Once you’ve configured your values.yaml, run the helm install command from the final step in your download portal:

Update Helm Installations

For subsequent updates to your Opal cluster, log back in to your download portal and select the Manual Updates tab at the top. Set the current and update versions from the dropdowns:

If you’re using a private registry, you’ll need to re-run the commands to pull, retag, and push images to your private registry. We recommend you run these via a script or other automation.

Finally, run the helm upgrade command from the final step in your download portal:

Migrate from a KOTS-Based Installation

If you previously installed Opal using KOTS and want to manage your deployment with Helm, you can perform a one-way migration. This will not cause any downtime for your cluster, but will not be reversible.

First, follow the Initial Setup instructions above. Once you reach Configure and Install via Helm, skip that section and follow the steps below instead.

Pull your cluster’s current Helm values into a local file:

helm get values opal-web -n <namespace> -o yaml > values-from-kots.yaml

Edit the image section in this values file:

If you’re using Opal’s image registry, use the following:

image:
  repository: proxy.replicated.com/proxy/opal-onprem/179751979675.dkr.ecr.us-east-2.amazonaws.com
  useReplicatedPullSecret: true

If you’re using a private image registry, use the following:

image:
  repository: <your private registry's hostname>
  useReplicatedPullSecret: false

Scale down the KOTS pods:

kubectl -n opal-onprem scale deploy kotsadm --replicas=0
kubectl -n opal-onprem scale sts kotsadm-minio --replicas=0
kubectl -n opal-onprem scale sts kotsadm-rqlite --replicas=0

Use helm list to check the currently installed version of opal:

$ helm list -n <namespace>
NAME    	NAMESPACE  	REVISION	UPDATED	STATUS  	CHART                       	APP VERSION        
opal-web	opal-onprem	1       	-      	deployed	opal-web-1.944.0-sha-8d4530d	1.944.0-sha-8d4530d

Copy the value under APP VERSION for the step below

Run a Helm upgrade to take over the chart’s resources:

helm upgrade opal-web oci://registry.replicated.com/opal-onprem/stable/opal-web -n <namespace> --version <current app version> --values values-from-kots.yaml --take-ownership

Once this is complete, you can update your Helm installation in the future by following the instructions in Update Helm Installations above.

You can also finish cleaning up the kubernetes resources created by KOTS by running the following:

kubectl -n <namespace> delete deployment kotsadm;
kubectl -n <namespace> delete statefulset kotsadm-minio;
kubectl -n <namespace> delete statefulset kotsadm-rqlite;
kubectl -n <namespace> delete service kotsadm;
kubectl -n <namespace> delete service kotsadm-minio;
kubectl -n <namespace> delete service kotsadm-rqlite;
kubectl -n <namespace> delete service kotsadm-rqlite-headless;
kubectl -n <namespace> delete persistentvolumeclaim kotsadm-minio-kotsadm-minio-0;
kubectl -n <namespace> delete persistentvolumeclaim kotsadm-rqlite-kotsadm-rqlite-0;
kubectl -n <namespace> delete role kotsadm-role;
kubectl delete clusterrolebinding kotsadm-rolebinding;
kubectl delete clusterrole kotsadm-role;
kubectl -n <namespace> delete serviceaccount kotsadm;