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 thenevisadmin4-crd
Helm chart. - Read permissions for cluster scoped
CustomResourceDefinition
objects, this is used to verifycert-manager
andnevisadmin4-crd
installation. cert-manager
and thenevisadmin4-crd
chart can be installed separately, then only read permissions are necessary.
- Necessary for
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
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
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