Understanding OpsChain configuration variables
This guide describes the various configuration options that can be modified in OpsChain's values.yaml file before installing OpsChain along with their default values. The majority of these settings can be modified post-installation via the OpsChain GUI or API, however, some settings can only be modified before installation and will only have an effect after redeploying OpsChain.
Your values.yaml file might come with settings that are not mentioned in this document, these are internal OpsChain configuration and SHOULD NOT be modified unless explicitly recommended to do so.
Mandatory encryption and password settings
The settings to secure your OpsChain installation must be provided before installing the application. These are unique keys that should not be modified after the initial installation and not shared with anyone.
You can generate a random key of specific length for the following settings with:
openssl rand -hex <key_length>
You can then copy the value and paste it into your setting's value. DO NOT reuse the same value for different settings.
| Variable name | Description |
|---|---|
| OPSCHAIN_DETERMINISTIC_KEY | The key OpsChain will use for encrypting its data, must be at least 32 characters long |
| OPSCHAIN_IMAGE_REGISTRY_PASSWORD | The password that OpsChain should use when communicating with its internal image registry, must be at least 8 characters long. |
| OPSCHAIN_KEY_DERIVATION_SALT | The key OpsChain will use for generating its cryptography keys, must be at least 32 characters long. |
| OPSCHAIN_LDAP_PASSWORD | The password that OpsChain will use when communicating with its LDAP server, must be at least 8 characters long. |
| OPSCHAIN_PRIMARY_KEY | The primary key OpsChain will use for encryption, must be at least 32 characters long. |
| PGPASSWORD | The password for accessing OpsChain's database, must be at least 8 characters long. |
Mandatory secret vault settings
If you are using the default secret vault provided by OpsChain, you must define the hostname its UI will be accessible at. You can do so by modifying the global.secretVaultExternalHostName setting in your values.yaml file.
By default, OpsChain will issue a self-signed certificate for accessing the default secret vault and this certificate must be trusted by anyone accessing it. You can extract the self-signed certificate from the opschain-ca-key-pair secret by running the following command:
kubectl -n opschain get secret opschain-ca-key-pair -o jsonpath="{.data.ca\.crt}" | base64 -d > opschain-ca.pem
Alternatively, you can provide a custom certificate that will be used for accessing the default secret vault by creating a Kubernetes secret containing the certificate and private key and modifying the secretVault.externalCertificateSecretName setting in your values.yaml file to the name of your secret. The certificate you provide must include a DNS subjectAlternativeName that matches the value in global.secretVaultExternalHostName.
You can use the following command to create a Kubernetes secret containing the certificate and private key:
kubectl -n opschain create secret tls my-custom-certificate --cert=path/to/tls.cert --key=path/to/tls.key
Optional configuration
API settings
These settings define how the OpsChain API will be exposed on the network. Modifying any of these settings requires a full redeployment of the OpsChain application.
OPSCHAIN_API_CERTIFICATE_SECRET_NAME
Default value: none
The Kubernetes TLS secret name containing a custom certificate to be used for the HTTPS listener. When this is set, OPSCHAIN_API_HOST_NAME must also be configured. Learn more.
OPSCHAIN_API_EXTERNAL_PORT
Default value: 3000
The port that will be exposed for accessing the OpsChain API service.
OPSCHAIN_API_HOST_NAME
Default value: none
The host name that will be configured for the OpsChain API HTTPS listener. This is not required for HTTP access to the API, only for HTTPS access. Learn more
OPSCHAIN_INSECURE_HTTP_PORT_ENABLED
Default value: true
Defines whether the OpsChain Ingress should provide an insecure HTTP port to be used for accessing the OpsChain API. Learn more.
Authentication settings
OPSCHAIN_AUTH_STRATEGY
Default value: ldap
Accepted values: ldap, local
This setting can be updated via system configuration post installation.
Defines which authentication strategy will be used for user authentication. Currently, only one can be active at any given moment.
For the changes to this setting to take effect, the OpsChain API must be restarted.
Users that are authenticated via LDAP will not be able to login when this variable is set to local and vice-versa.
Change running settings
OPSCHAIN_API_WORKER_SCALE
Default value: 2
The number of worker pods that will be deployed to process change and workflow steps.
The number of steps that can be processed by OpsChain is limited to the number of threads per worker multiplied by this value. E.g. Two workers with five threads per worker can process ten steps concurrently.
OPSCHAIN_MINTMODEL_API_SCALE
Default value: 5
The number of parallel MintModel-rendering pods. These are the pods responsible for concretising the MintModels into actionable files. Without them, your instance will not be able to generate MintModels.
OPSCHAIN_PARALLEL_CHANGE_WORKER_STEPS
Default value: 10
The number of steps that can be run in parallel for a single change.
This option should not be set to a value greater than the number of threads per worker multiplied by the number of workers.
OPSCHAIN_REPO_FOLDER
Default value: .opschain
This setting can be updated via system configuration post installation.
Folder in the Git repositories where OpsChain properties and custom Dockerfiles will be imported from when running a change. Can be overriden by projects, environments, assets or on a per-change basis.
OPSCHAIN_SSH_KNOWN_HOSTS_CONFIG_MAP
Default value: none
OpsChain uses a bundled SSH known_hosts file for authentication. It has certificates for a number of common source code hosting platforms, including:
- Bitbucket
- GitHub
- GitLab
If you'd like to have support for other platforms, you can create a new config map with the desired contents and update this setting to use your custom config map name instead.
You can use the following command to export the bundled known_hosts file to a YAML file as a template:
kubectl -n opschain get ConfigMap opschain-ssh-known-hosts -o yaml > custom-opschain-ssh-known-hosts.yaml
You can then edit the exported resource, ensure you update the metadata.name field to a different config map name, and then update the file contents under the known_hosts key. Once the resource definition has been updated, use kubectl to create the custom config map:
kubectl -n opschain apply -f custom-opschain-ssh-known-hosts.yaml
Once the custom config map has been created, you can update the OPSCHAIN_SSH_KNOWN_HOSTS_CONFIG_MAP setting to use the custom config map name instead.
OPSCHAIN_THREADS_PER_WORKER
Default value: 5
Minimum value: 2
The number of threads each worker process will run. Note that increasing this number further may actually decrease concurrency due to context switching. We recommend that you consider increasing the number of workers before considering increasing this value.
OPSCHAIN_TRACE
Default value: false
If set to true, additional logging will be generated when changes are run, allowing for more detailed debugging of changes.
Image building settings
These settings define how OpsChain will build the Docker images for running changes.
OPSCHAIN_IMAGE_BUILD_ROOTLESS
Default value: true
Whether to use the Buildkit rootless mode for the image build container.
OPSCHAIN_IMAGE_BUILD_CACHE_VOLUME_SIZE
Default value: 10Gi
Volume claim size for the image build container cache.
Image registry settings
External image registry settings
OPSCHAIN_DOCKER_USER
Default value: none
Docker Hub username to be used for accessing the OpsChain images on the external image registry.
OPSCHAIN_DOCKER_PASSWORD
Default value: none
Docker Hub password/token to be used for accessing the OpsChain images on the external image registry.
Internal image registry settings
OPSCHAIN_IMAGE_REGISTRY_HOST
Default value: opschain-image-registry.local.gd
Internally used hostname that needs to resolve to the Kubernetes node, but be different to the API hostname.
OPSCHAIN_IMAGE_REGISTRY_VOLUME_SIZE
Default value: 10Gi
Volume claim size for the internal step image registry image storage volume.
Ingress settings
OPSCHAIN_INGRESS_TLS_PORT
Default value: 3443
Ingress service port defined in the Kong controller. Used by the internal image registry and for HTTPS access to the API and the default secret vault.
Kubernetes deployment settings
OPSCHAIN_KUBERNETES_NAMESPACE
Default value: opschain
The Kubernetes namespace where OpsChain will be deployed.
OPSCHAIN_RUNNER_NODE_SELECTOR
Default value: {}
This setting can be updated via system configuration post installation.
Kubernetes nodeSelector value that will be used to select the Kubernetes node where step runner pods will be deployed. Must be specified as a JSON string.
Use the default value unless running on a multi-node cluster.
LDAP/AD settings
OpsChain provides an LDAP server for authentication out-of-the-box. If you'd prefer to use your own LDAP server, follow the OpsChain LDAP guide to alter these settings. All the default values shown below refer to the out-of-the-box LDAP server that OpsChain provides.
All these settings can be updated via system configuration post installation.
OPSCHAIN_LDAP_ADMIN
Default value: cn=admin,dc=opschain,dc=io
LDAP/AD administrator DN to connect to.
Note: As OpsChain does not write to the LDAP database, this only needs to be a DN with permission to search all users and groups.
OPSCHAIN_LDAP_BASE_DN
Default value: dc=opschain,dc=io
LDAP/AD base DN value.
OPSCHAIN_LDAP_DOMAIN
Default value: opschain.io
LDAP/AD domain.
OPSCHAIN_LDAP_GROUP_BASE
Default value: ou=groups,dc=opschain,dc=io
LDAP/AD base DN to search for groups.
OPSCHAIN_LDAP_GROUP_ATTRIBUTE
Default value: member
LDAP/AD group attribute containing OpsChain user DNs.
OPSCHAIN_LDAP_HC_USER
Default value: healthcheck
To verify the LDAP server is available, OpsChain performs a regular query of the LDAP database for the username supplied here.
Note: If you do not wish to perform this check, leave this blank.
OPSCHAIN_LDAP_HOST
Default value: opschain-ldap
LDAP/AD host name (or IP address).
OPSCHAIN_LDAP_PORT
Default value: 389
LDAP/AD host port to connect to.
OPSCHAIN_LDAP_USER_BASE
Default value: ou=users,dc=opschain,dc=io
LDAP/AD base DN to search for users.
OPSCHAIN_LDAP_USER_ATTRIBUTE
Default value: uid
LDAP/AD user attribute used as the OpsChain username.
Secret vault settings
OpsChain provides an out-of-the-box secret vault that can be used to store secure property information. However, you can also use an external secret vault by providing the settings below.
Vault settings can be overriden at a project, environment or asset level, allowing you to use different vaults for each of these.
You can provision the default secret vault on installation and configure individual projects, environments or assets to access external vaults.
OPSCHAIN_USE_DEFAULT_VAULT
Default value: true
Whether OpsChain should provision the default secret vault on installation. If this is set to true, the settings below will be automatically configured by OpsChain. If this is false, you can provide a custom secret vault configuration with these settings.
When using the default secret vault, you must provide an external hostname for it in the values.yaml file, as described in the mandatory secret vault settings section.
OPSCHAIN_VAULT_ADDRESS
Default value: none
The address of the external secret vault that OpsChain will use, including the port, e.g http://vault.example.com:8200.
OPSCHAIN_VAULT_AUTH_METHOD
Default value: none
Accepted values: token, userpass, ldap
The authentication method that OpsChain will use to authenticate with the external secret vault.
OPSCHAIN_VAULT_TOKEN
Default value: none
The token that OpsChain will use to authenticate with the external secret vault. Required if the authentication method is token.
When using the default secret vault, the token will be automatically generated by OpsChain and is necessary for root access to the secret vault. You can extract the token from the opschain-vault-config secret by running the following command:
kubectl -n opschain get secret opschain-vault-config -o jsonpath="{.data.OPSCHAIN_VAULT_TOKEN}" | base64 -d
Note that this token provides root access to the secret vault and should be kept secure.
OPSCHAIN_VAULT_USERNAME
Default value: none
The username that OpsChain will use to authenticate with the external secret vault. Required if the authentication method is userpass or ldap.
OPSCHAIN_VAULT_PASSWORD
Default value: none
The password that OpsChain will use to authenticate with the external secret vault. Required if the authentication method is userpass or ldap.
OPSCHAIN_VAULT_MOUNT_PATH
Default value: none
The mount path for the KV secret store in the external secret vault.
OPSCHAIN_VAULT_USE_MINT_ENCRYPTION
Default value: true
Whether to use OpsChain's encryption to encrypt the values before storing them in the external secret vault. If this is set to true, the values will be encrypted twice.
OPSCHAIN_VAULT_CLIENT_OPTIONS
Default value: none
A hash of options to pass to the external vault client, in JSON format. Refer to the Vault Ruby Client Gem usage instructions for the available options.
Post-install system configuration
When starting OpsChain for the first time, the settings above will be stored in OpsChain's database and might be updated via the OpsChain GUI or API. See the API documentation for more details.