nmaas Installation Guide
Requirements
To install nmaas into an existing Kubernetes cluster, the following requirements must be met:
- Kubernetes version
>=1.16 - Helm v3 support in the Kubernetes cluster
- Existing ingress controller, preferably with a default TLS certificate set (more information available below)
- An integration with an external load-balancer or MetalLB for bare-metal deployments, so that IPs can be assigned to
LoadBalancerservices
nmaas Components
nmaas is comprised of multiple components, and a brief description for each one is provided in the self-hosting introduction page.
Installation
The nmaas installation is a two-step process - first an instance of GitLab must be deployed and configured, and then nmaas itself. The two components cannot be deployed at the same time, since during the deployment process nmaas requires a GitLab API key to be specified.
GitLab Installation
GitLab can be deployed using the official Helm chart whose source code is also publicly available. Note that GitLab requires at least 8GB of memory to run.
No More Bundled PostgreSQL/Redis/Object Storage
Unlike older versions of the chart, GitLab 10.3.1 no longer bundles PostgreSQL, Redis, or object storage (MinIO) as subcharts — GitLab itself does not supply these. A PostgreSQL instance, a Redis instance, and an S3-compatible object store must each be deployed and configured separately before installing GitLab, using GitLab's own external-database/external-storage configuration options shown below. This guide only documents the GitLab-side values and secrets needed.
If using a PostgreSQL instance with a non-root user, the following extensions must be enabled beforehand in the target GitLab database:
- btree_gist
- pg_trgm
GitLab Version
10.3.1 is the latest version of the GitLab chart that has been tested with the latest version of nmaas.
GitLab needs to be told how to reach your PostgreSQL/Redis instances and object storage via Kubernetes secrets:
The object storage connection details are passed as secrets containing GitLab-specific config formats, not plain key/value pairs. Consult GitLab's own object storage documentation for the exact set of buckets it expects to find (LFS, artifacts, uploads, packages, container registry, and optionally backups):
| rails-storage-connection.yaml | |
|---|---|
| registry-storage-connection.yaml | |
|---|---|
GitLab Values
Below is a snippet of the mandatory parameters that must be specified during GitLab's deployment, so that it will be compatible with nmaas. The complete list of supported value parameters is available in the official GitLab Helm chart Git repository.
| gitlab-values.yaml | |
|---|---|
| |
TLS Secret Must Exist in GitLab's Namespace
Classic Ingress TLS secretName references only support same-namespace secrets — this is a core Kubernetes Ingress limitation, not specific to GitLab or Cilium. Make sure <MY_TLS_SECRET> exists in the same namespace GitLab is deployed into before installing.
global.gatewayApi.enabled: false Alone Does Not Suppress Envoy Gateway
Setting global.gatewayApi.enabled: false disables Gateway API routing but does not, by itself, stop the chart from installing its bundled Envoy Gateway subchart — global.gatewayApi.installEnvoy: false must be set explicitly too, otherwise a stray envoy-gateway pod will get deployed.
Note that the secrets referenced by global.initialRootPassword.secret, global.psql.password.secret, and global.smtp.password.secret must be created manually, pointing at the credentials for whichever PostgreSQL and SMTP instances are deployed or configured for GitLab.
GitLab Email Sending
nmaas does not rely on email sending via GitLab, so both the email and smtp sections in the value files can be left with their default values - unconfigured.
Once all configuration parameters have been specified, GitLab can be installed using the following Helm v3 command:
GitLab Deployment Duration
Please allow more than 15 minutes for GitLab to be deployed, depending on hardware configuration and current resource utilization.
Once GitLab has been deployed, it can be accessed by navigating to gitlab.<TLD>, where TLD is the value specified for the .Values.global.hosts.domain parameter.
GitLab Public Exposure
Note that after deployment, by default, anyone can register to the newly deployed GitLab instance. This can be configured by logging in as the root GitLab user.
Users are advised to determine whether public exposure of the GitLab web interface is needed at all. nmaas' GitLab integration can work even if only public access to the GitLab SSH interface is provided, since repository cloning always relies on SSH as the transport protocol.
To create a GitLab API token that can be used by nmaas, perform the following steps:
- Login to GitLab using the root account;
- Click on the avatar image in the top right corner and select
Settings; - From the left-hand navigation menu choose
Access Tokens; - Create a new access token with no expiration date by simply leaving the
Expires atfield empty, and assigning all available scopes; - Write down the API token, it will be needed shortly.
SSH Access to GitLab Repositories
GitLab supports SSH access to any created repositories. If you want to allow your users to clone the repositories where their application configuration is stored, then you will have to alter the GitLab Shell service, and change its type to LoadBalancer, so that a routable IP address will be assigned to it.
nmaas Installation
nmaas Values
The source code for the nmaas Helm chart is publicly available on nmaas-platform/nmaas-chart. The chart's values.yaml and README.md provide the full, authoritative list of configurable parameters for a given chart version — refer to those directly when preparing a custom values file.
nmaas Version
2.0.6 (chart version, application version 1.10.0) is the latest version of nmaas that has been tested with this guide.
The following manual steps must be performed before deploying nmaas:
-
Creating a private/public SSH keypair so that nmaas Platform can access nmaas Helm:
-
The secrets for the SP, API, and admin password:
-
Create the nmaas Janitor secret containing the GitLab API key, generated previously:
-
Create the JWT signing secret. This is required but undocumented in the chart's own
values.yamlcomments —platform.properties.jwt.secretName(defaultnmaas-jwt) must already exist before install; the chart does not generate it automatically, and install will fail withsecret "nmaas-jwt" not foundif it's skipped. Each key must be at least 96 characters: -
Create the SMTP secret for the
nmaas-postfixcomponent. This is required regardless of whether real external SMTP relay is needed; if not, placeholder values are sufficient:
Once the required secrets have been created, nmaas can be deployed using the following command (make sure to deploy in the same namespace as GitLab):
It is recommended to use nmaas-system as the namespace where nmaas and all associated components (PostgreSQL, GitLab) will be deployed.
nmaas Deployment Time
Please allow at least 10 minutes for nmaas to be fully deployed, depending on hardware configuration and resource utilization.
Verifying the Installation
You can verify that nmaas has been successfully deployed by navigating to its ingress URL from your browser, logging in as the admin user and selecting Settings -> Monitoring. From this location, you can execute checks for all the required components of nmaas. A fully functional installation should return a successful response for all monitors.
GitLab Must Allow Local-Network Webhooks Before Any Application Can Be Deployed
Every application deployment goes through nmaas registering a webhook on a GitLab project it creates, pointing at http://nmaas-platform:<port>/api/v1/gitlab/webhooks/<id> — an internal Kubernetes Service hostname. GitLab's SSRF-protection setting blocks webhooks targeting local/private network addresses by default, so without this change, every single application deployment will fail at the configuration step with GITLAB: Invalid url given Unprocessable Entity (GitLabConfigHandler.addWebhookToProject), no matter which application or domain. To allow for Local-Network webhooks, log in as GitLab root:
Admin Area → Settings → Network → Outbound requests → enable "Allow requests to the local network from webhooks and integrations" (and, while there, the adjacent "Allow requests to the local network from system hooks" is worth enabling too).
This can also be verified/set via the API:
Administrator Information
For more detailed instructions, refer to the Domain Admin Guide
Creating New Domains
Creating a new customer domain within nmaas is a two-step process:
- First, the new domain should be added from the nmaas web interface. The following steps should be performed.
- Login to the nmaas Portal as the administrator user (the default administrator username is
adminand the desired password is passed as a installation parameter); - Navigate to
Settings -> Domains; - Click the
Addbutton and enter the required parameters specific to the newly created domain:Name- full name of given domain (e.g.Test Domain)Codename- abbreviated name of the domain (e.g.testdom)Kubernetes namespace(Optional) - a namespace dedicated for this domain to be created in the next stepKubernetes storage class(Optional) - a specific storage class to be used for persistent volumes created in this domain (typically should be left blank)Kubernetes ingress class(Optional) - a ingress class supported by the ingress controller deployed for this domain (should be left blank if a single common controller supports all the domains)External service domain- a base URL for accessing all applications deployed in this domain (typically should contain the Codename and the URL of nmaas itself, e.g.testdom.nmaas.example.com)DCN deployment type- by default should be set toManualDCN status- by default should be set toConfiguredCustomer networks(to be removed) - list of network prefixes to which applications deployed in this domain should have access (thought this parameter is currently mandatory it is not used for any automated actions so any initial values can be provided)
- Click the
Submitbutton to create the domain
- Login to the nmaas Portal as the administrator user (the default administrator username is
-
Then, the following operations should be performed within the cluster:
- Create a new Kubernetes namespace with the same name as the domain
-
Create a new MetalLB range with the same name as the new customer domain, and set that addresses should not be automatically assigned. To accomplish this, the existing MetalLB ConfigMap can simply be edited to include the new configuration block. An example MetalLB
ConfigMapis available below:config.yaml With the above configuration, whenever a LoadBalancer Kubernetes Service is created, it will be assigned an address from the default-pool, unless the
annotation metallb.universe.tf/address-pool: domain1is present, in which case an address from the domain1 pool will be allocated.Legacy MetalLB Configuration
The
ConfigMap-based example above is kept from earlier versions of this guide and applies only to MetalLB releases older than0.13. Newer MetalLB releases ignore thisConfigMapand are configured exclusively through custom resources (IPAddressPoolwithautoAssign: false, together with anL2Advertisement). This step has not been re-validated against current MetalLB releases. For the equivalent configuration, refer to the MetalLB configuration documentation and the ConfigMap-to-CRD migration guide. -
Deploy a new ingress controller in the new domain namespace, with an ingress class that will match the name of the domain.
DCN Configured Must Be Manually Confirmed
Even with DCN status set to Configured in the domain creation form above, applications deployed into the domain will hang indefinitely at "Verifying secure connectivity to your equipment" unless the domain's DCN configuration is also explicitly confirmed after the domain is created.
Confirm it via the Portal (Settings -> Domains -> edit the domain -> DCN configured checkbox).
Additional Documentation
An online user guide is available at nmaas User Guide page.
Information about the nmaas applications deployment and configuration process and the nmaas portfolio is available on the nmaas Tools page.
In case of any questions please contact the nmaas Team at [email protected].