Installation automation on OpenShift

If you want to deploy Nevis onto a Cloud infrastructure, we recommend a Kubernetes-based installation. This installation is based on the Docker containerization and Kubernetes orchestration technologies.

For a general overview of the Nevis-on-Kubernetes deployment solution, check Kubernetes Deployment (Cloud).

In this installation tutorial, you will set up a complete Nevis environment on OpenShift with minimal configuration.

It uses Helm with the help of a bash script to install nevisAdmin4 with all it's dependencies with minimal inputs from the user.

Prerequisites

The following requirements have to be in place before the installation:

• Linux or macOS
• oc cli
• Context is set for the OpenShift cluster
• Domain where nevisAdmin 4 will be available and permission to create a DNS A record for it.
  • Until the DNS A record is created, port forwarding can be used to access nevisAdmin 4.
• Cluster scoped permission for the cluster
  • Necessary for cert-manager installation, and the nevisadmin4-crd Helm chart.
  • Read permissions for cluster scoped CustomResourceDefinition objects, this is used to verify cert-manager and nevisadmin4-crd installation.
  • cert-manager and the nevisadmin4-crd chart can be installed separately, then only read permissions are necessary.

Installation

Simply run the provided script and follow the instructions: openshift-installer.sh

Installed components

The following components will be installed on the cluster:

• cert-manager with the official Helm chart
• nevisadmin4-crd Helm chart
• nevisadmin4 Helm chart
  • includes ingress-nginx Helm chart
  • includes Gitea Helm chart
  • includes MariaDB Helm chart from Bitnami

info

The installed MariaDB instance only supports a single primary replica. For this reason it's recommended to use a separate managed database for the deployed Nevis components such as nevisIDM.

Installation process

During the installation process the following steps will be performed:

• Verifying the correct OpenShift cluster is set as the context.
• Reads user input for the necessary variables.
• Push images to the internal container registry.
• Installs Helm if it's not present.
• Deploys cert-manager if not already present on the cluster. It is used to create certificates both for internal use, and for creating valid certificates with Let's Encrypt.
• Deploys the nevisadmin4-crd helm chart if the crds are not already present on the cluster.
• Deploys nevisadmin4 Helm chart configured to use the Gitea and MariaDB instance provided by the same chart. The chart will also import example projects and inventories as the last step of the installation.

Verifying the deployment

After the deployment is finished, a DNS A record has to be created with the given DOMAIN to the IP of the newly created nginx Loadbalancer service. After that nevisAdmin 4 can be accessed at DOMAIN/nevisadmin.

Until the DNS record is in place port forwarding can also be used to access the application:

oc port-forward -n $RELEASE_NAMESPACE nevisadmin4-0 28111:9080

then visiting 127.0.0.1:28111/nevisadmin

Arguments & flags

The configuration options can also be provided using the command line.

Arguments	Description
--namespace	Namespace where nevisAdmin 4 will be installed
--domain	The domain where nevisAdmin 4 will be accessible, for example 'nevis.os3434.com'. This domain will be used for a DNS A record with the IP of the created nginx loadbalancer
--container-registry	Container registry to push the images to, for example 'os.icr.io'
--registry-username	Username for the registry
--registry-password	Password for the registry
--cloudsmith-password	Password for the nevissecurity/lts-202405 Cloudsmith repository, you can get the password by selecting one of the docker images in 'https://portal.nevis.net/portal/secure/releases/lts-202405`
--add-nginx-node-port	Configures the nginx instance to use NodePort instead of LoadBalancer
--add-nginx-load-balancer	Configures the nginx instance to use LoadBalancer instead of NodePort
--upgrade	Upgrades an exisitng installation

Troubleshooting

Cleanup

Delete the namespace or run the following commands:

helm uninstall $RELEASE_NAME -n $RELEASE_NAMESPACE
oc delete pvc --all -n $RELEASE_NAMESPACE

No external IP

On certain private clusters the IP assigment of the loadbalancer is not automatic, contact the platform team of the cluster for support. It might be required to use NodePort service and expose nginx directly instead of using a loadbalancer, for this rerun this script with the option --add-nginx-nodeport.

Manual installation

Instead of running the script it's also possible to run the necessary commands manually:

Setting environment variables

# Autogeneratd passwords for the installation
NEVISADMIN_PASSWORD=$(openssl rand -base64 48 | tr -dc '[:alnum:]' | head -c 16)
DB_ROOT_PASSWORD=$(openssl rand -base64 48 | tr -dc '[:alnum:]' | head -c 16)
DB_APP_PASSWORD=$(openssl rand -base64 48 | tr -dc '[:alnum:]' | head -c 16)
DB_SCHEMA_PASSWORD=$(openssl rand -base64 48 | tr -dc '[:alnum:]' | head -c 16)
GIT_PASSWORD=$(openssl rand -base64 48 | tr -dc '[:alnum:]' | head -c 16)
# Username for the Gitea admin user
GIT_USER=root
# Username for the MariaDB root user
DB_ROOT_USER=root
# Database for the MariaDB root user
DATABASE_HOST=mariadb
# Release name for the Helm installation
RELEASE_NAME=nevisadmin4
# The domain where nevisAdmin 4 will be accessible, for example 'nevis.os3434.com'. This domain will be used for a DNS A record with the IP of the nginx loadbalancer.
DOMAIN=
# Namespace where nevisAdmin 4 will be installed, it has to already exists
RELEASE_NAMESPACE=
# Container registry to push the images to, for example 'os.icr.io'
CONTAINER_REGISTRY=
# Username for the registry
REGISTRY_USERNAME=
# Password for the registry
REGISTRY_PASSWORD=
# Password for the nevissecurity/lts-202405 Cloudsmith repository, you can get the password by selecting one of the docker images in 'https://portal.nevis.net/portal/secure/releases/lts-202405`
CLOUDSMITH_PASSWORD=
# UID for the Gitea user. The UID has to be inside the range specified by 'openshift.iosa.scc.uid-range' annotation on the namespace. 
GITEA_RUN_USER=

Push docker images

Upload nevis docker images

Install cert-manager

If cert-manager is not already installed on the cluster, run:

helm install cert-manager cert-manager --create-namespace --namespace cert-manager --repo https://charts.jetstack.io --version 1.9.2 --wait --set installCRDs=true

Install nevisAdmnin 4

# Install nevisadmin4-crd chart
helm install nevisadmin4-crd nevisadmin4-crd --repo https://dl.cloudsmith.io/$CLOUDSMITH_PASSWORD/nevissecurity/lts-202405/helm/charts/

# Prepare registry secret
oc create secret docker-registry registry-secret --docker-server="$CONTAINER_REGISTRY" --docker-username="$REGISTRY_USERNAME" --docker-password="$REGISTRY_PASSWORD" -n "$RELEASE_NAMESPACE"

# Prepare nginx service account
oc create serviceaccount nevisadmin4-nginx -n "$RELEASE_NAMESPACE"
oc adm policy add-scc-to-user privileged -z nevisadmin4-nginx -n "$RELEASE_NAMESPACE"

# Generate keys
ssh-keygen -t ecdsa -C "kubernetes" -m PEM -P "" -f neviskey

helm install $RELEASE_NAME nevisadmin4 --wait --timeout 10m --repo https://dl.cloudsmith.io/$CLOUDSMITH_PASSWORD/nevissecurity/lts-202405/helm/charts/ -n "$RELEASE_NAMESPACE" \
    --set image.repository="$CONTAINER_REGISTRY" \
    --set git.repositoryUrl=ssh://$GITEA_RUN_USER@gitea-ssh:2222/$GIT_USER/deploy.git\
    --set git.username=$GIT_USER \
    --set image.imagePullSecretName=registry-secret \
    --set git.password="$GIT_PASSWORD" \
    --set database.host=$DATABASE_HOST \
    --set database.root.username=$DB_ROOT_USER \
    --set database.root.password="$DB_ROOT_PASSWORD" \
    --set nevisAdmin4.database.schemaUserPassword="$DB_SCHEMA_PASSWORD" \
    --set nevisAdmin4.database.applicationUserPassword="$DB_APP_PASSWORD" \
    --set nevisAdmin4.database.enableSSL=false \
    --set nevisAdmin4.domain="$DOMAIN" \
    --set nevisAdmin4.password="$NEVISADMIN_PASSWORD" \
    --set nevisAdmin4.podSecurityContext.fsGroup=null \
    --set bootstrap.nevisAdmin4.enabled=true \
    --set bootstrap.gitea.enabled=true \
    --set gitea.enabled=true \
    --set gitea.ingress.enabled=true \
    --set 'gitea.ingress.hosts[0].host'="$DOMAIN" \
    --set 'gitea.ingress.hosts[0].paths[0].path'="/gitea(/|$)(.*)" \
    --set 'gitea.ingress.hosts[0].paths[0].pathType'=ImplementationSpecific \
    --set 'gitea.ingress.tls[0].hosts[0]'="$DOMAIN" \
    --set 'gitea.ingress.tls[0].secretName'=gitea-tls \
    --set gitea.ingress.annotations."kubernetes\.io/ingress\.class"="nginx-nevisadmin4-$RELEASE_NAMESPACE" \
    --set gitea.gitea.config.server.ROOT_URL=https://"$DOMAIN"/gitea/ \
    --set gitea.gitea.config.database.USER=$DB_ROOT_USER \
    --set gitea.gitea.config.database.PASSWD="$DB_ROOT_PASSWORD" \
    --set gitea.gitea.admin.username=$GIT_USER \
    --set gitea.gitea.admin.password="$GIT_PASSWORD" \
    --set gitea.gitea.config.RUN_USER="\"$GITEA_RUN_USER\"" \
    --set gitea.podSecurityContext.fsGroup="$GITEA_RUN_USER" \
    --set gitea.containerSecurityContext.runAsUser="$GITEA_RUN_USER" \
    --set maria.enabled=true \
    --set maria.auth.rootPassword="$DB_ROOT_PASSWORD" \
    --set maria.auth.username=gitea \
    --set maria.primary.podSecurityContext.enabled=false \
    --set maria.primary.containerSecurityContext.enabled=false \
    --set maria.auth.password="$DB_ROOT_PASSWORD" \
    --set git.privateKey64="$(cat neviskey | base64 | tr -d '\n')" \
    --set git.publicKey64="$(cat neviskey.pub | base64 | tr -d '\n')" \
    --set nginx.enabled=false \
    --set nginx.controller.scope.enabled=true \
    --set nginx.controller.scope.namespace="$RELEASE_NAMESPACE" \
    --set nginx.controller.ingressClassResource.enabled=false \
    --set nginx.controller.ingressClass=nginx-nevisadmin4-"$RELEASE_NAMESPACE"  \
    --set nginx.controller.ingressClassResource.name=nginx-nevisadmin4-"$RELEASE_NAMESPACE" \
    --set nginx.rbac.scope=true \
    --set nginx.serviceAccount.create=false \
    --set nginx.serviceAccount.name=nevisadmin4-nginx

# The Gitea instance autogenerates the used keys, which we have to set for the nevisAdmin 4 instance
helm upgrade nevisadmin4 nevisadmin4 --reuse-values --wait --repo https://dl.cloudsmith.io/$CLOUDSMITH_PASSWORD/nevissecurity/lts-202405/helm/charts/ -n "$RELEASE_NAMESPACE" \
    --set git.knownHosts64="$(echo gitea-ssh "$(oc exec gitea-0 -c gitea -n "$RELEASE_NAMESPACE" cat /data/ssh/gitea.rsa.pub)" | base64 | tr -d '\n')"

# Adding ingress-nginx loadbalancer to the installation, this is done in a seperate step in case external IP has to be assigned manually"
helm upgrade nevisadmin4 nevisadmin4 --reuse-values --repo https://dl.cloudsmith.io/$CLOUDSMITH_PASSWORD/nevissecurity/lts-202405/helm/charts/ -n "$RELEASE_NAMESPACE" \
    --set nginx.enabled=true