Installation and Deployment

Aurelius Atlas is distributed as a Helm chart. This allows for easy installation and deployment on any cloud provider or on-premises Kubernetes cluster.

All distributions of Aurelius Atlas are available on GitHub:

Infrastructure Requirements

The following are the minimal infrastructure requirements for deploying Aurelius Atlas:

Prerequisites

Before you begin the installation process, ensure that you have the following prerequisites:

First Time Installation

Once you have your cluster and prerequisites set up, you can install Aurelius Atlas using the Helm chart or Docker Compose. The following sections will guide you through the process.

Configuration Manager

Aurelius Atlas recommends Reflector for managing the configuration of the Kubernetes cluster. To install Reflector, run the following commands:

helm repo add emberstack https://emberstack.github.io/helm-charts
helm repo update
helm upgrade --install reflector emberstack/reflector

Certificate Manager and Issuer

To secure your deployment, Aurelius Atlas requires TLS certificates for your domain. Follow the steps below to set up the certificate manager and issuer.

Set Up Certificate Manager

First, you need to install a certificate manager to manage the TLS certificates for your domain.

Aurelius Atlas recommends using cert-manager for managing TLS certificates in Kubernetes.

To install cert-manager, run the following commands:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
    --namespace cert-manager \
    --create-namespace \
    --version v1.15 \
    --set installCRDs=true \
    --set global.leaderElection.namespace=cert-manager

On successful installation, you should see the following output:

NOTES:
cert-manager v1.15 has been deployed successfully

Set Up Issuer

Next, you need to set up an issuer to issue the TLS certificates for your domain.

Aurelius Atlas recommends using the letsencrypt-prod issuer for production deployments. The helm chart includes a default configuration for the letsencrypt-prod issuer. To set up the issuer with the default configuration, follow these steps:

1. Uncomment the content of the templates/prod_issuer.yaml file in the Helm chart.
2. Update {{ .Values.ingress.email_address }} in the values.yaml file with your email address.

Next, run the following command to install the issuer:

helm template -s templates/prod_issuer.yaml . | kubectl apply -f -

This sets up the letsencrypt-prod issuer with the default configuration in the cert-manager namespace. To verify that the issuer is set up correctly, run the following command:

kubectl get clusterissuer -n cert-manager

You should see the letsencrypt-prod issuer in the list of cluster issuers with a status of Ready.

NAME                                       READY   AGE
letsencrypt-clusterissuer-aurelius-atlas   True    24h

Ingress Controller

Next, you need to set up an ingress controller to route external traffic to your services.

Set Up Ingress Controller

Aurelius Atlas recommends using an NGINX ingress controller. To install the ingress controller, follow the steps below:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install nginx-ingress ingress-nginx/ingress-nginx \
    --set controller.publishService.enabled=true

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install nginx-ingress ingress-nginx/ingress-nginx \
    --set controller.publishService.enabled=true \
    --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-load-balancer-health-probe-request-path"=/healthz \
    --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-dns-label-name"=<label>

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install nginx-ingress ingress-nginx/ingress-nginx \
    --set controller.publishService.enabled=true

Set Up Certificate

Next, you need to set up a certificate for the ingress controller. To do this, follow the steps below:

1. Uncomment the content of the templates/certificate.yaml file in the Helm chart.
2. Update {{ .Values.ingress.dns_url }} in the values.yaml file with your DNS name.

Next, run the following command to install the certificate:

helm template -s templates/certificate.yaml . | kubectl apply -f -

This sets up the certificate for the ingress controller. To verify that the certificate is set up correctly, run the following command:

kubectl get certificate -n cert-manager

You should see the certificate in the list of certificates with a status of Ready.

NAME                          READY   AGE
aurelius-atlas-ingress-cert   True    24h

Set up DNS

If you are deploying Aurelius Atlas on a cloud provider, but want to use your own domain name, you can set up a DNS record to point to the Load Balancer's IP address. To find the IP address of the Load Balancer, run the following command:

kubectl get service -n ingress-nginx

The output will show the external IP address of the Load Balancer.

Elastic Cloud

Aurelius Atlas uses Elastic Cloud on Kubernetes (ECK) to manage its internal Elasticsearch cluster. To set up ECK, run the following commands:

kubectl create -f https://download.elastic.co/downloads/eck/2.13.0/crds.yaml
kubectl apply -f https://download.elastic.co/downloads/eck/2.13.0/operator.yaml

Zookeeper

Aurelius Atlas internally relies on Zookeeper. Please ensure that the Zookeeper dependencies are updated by running the following commands:

cd charts/zookeeper/
helm dependency update

Deploying Aurelius Atlas

Once you have set up the prerequisites and configured the necessary components, you are ready to deploy Aurelius Atlas.

Configure Values

Before deploying Aurelius Atlas, you need to configure the values in the values.yaml file. The values.yaml file contains the configuration settings for Aurelius Atlas.

The following are the key configuration settings that you need to update:

Deploy Helm Chart

To deploy Aurelius Atlas using the Helm chart, run the following commands:

helm dependency update
helm install --generate-name -n <namespace> -f values.yaml --wait --timeout 15m0s .

Accessing Aurelius Atlas

Once the deployment is complete, you can access Aurelius Atlas using the DNS name you configured earlier. To access the platform, open a web browser and navigate to https://<dns-name>/<namespace>/atlas/.

Default Credentials

By default, the following users are created:

For production deployments, the passwords for each user are randomized and stored in a Kubernetes secret. The helm chart includes a script to retrieve the passwords for each user. To retrieve the passwords, run the following command:

./get_passwords.sh <namespace>

This script will print the passwords for each user to the console.

Identity & Access Management

Integrating Azure Active Directory with Keycloak

Active Directory login is not enabled by default. To enable it in Aurelius Atlas, follow these steps:

• Register an application in Azure Active Directory. For more details, follow this guide: Azure AD integration.

• Update the values.yaml file

  Update the values.yaml file in the base folder to load a different Keycloak configuration. Set the {{ .Values.keycloak.realm_file_name }} key to realm_m4i_with_provider.json.

• Customize the realm configuration

  Update the realm configuration file (charts/keycloak/realms/realm_m4i_with_provider.json) by entering your credentials:

To enable active directory login on the keycloak UI:

• Navigate to the Keycloak administration console.
• Click "Identity providers" in the menu, then choose the desired provider from the dropdown menu.
• Set the Client ID and Client Secret. The rest of the settings can remain default.

Managing Users

In Aurelius Atlas, you have the flexibility to control user access through role-based permissions. Users can either have read-only access or read/edit permissions, depending on their role within the system. By default, all users are assigned the viewing role, but administrators can manage and modify roles as needed.

• Viewing Role (Default): Users with this role can view data but cannot make any changes.
• Editing Role: Users with this role have permission to edit data and perform updates.

User Access

Anybody with a company login can access Aurelius Atlas, when active directory login is enabled, provided that they have the user roles assigned. (See section User Roles and Permissions)

For administrators who need more control over user registration, it’s also possible to manually create users directly within the Keycloak UI. For more information please visit the official Keycloak documentation.

Managing Roles in Keycloak UI

For organizations using Azure Active Directory (AAD) role assignments can be managed centrally in AAD, making it easier to maintain consistent user and role configurations across the organization.

Administrators can also manage user roles through the Keycloak Admin UI.

1. In the Keycloak Admin Console, navigate to the Users section.
2. Select the desired user and go to the Role Mappings tab.
3. Assign DATA_STEWARD to grant the user editing rights, or remove roles to make it a read-only user.

User Roles and Permissions