Deploying OpenIAM with Terraform
This guide describes how to deploy OpenIAM with Helm and Terraform.
Prerequisites
Install Terraform. If it is not already installed (visit terraform.io for other distributions).
Modify
terraform.tfvars. Set the value of the ‘app_name’ variable INterraform.tfvars to be the same as theAPP_NAMEvariable inenv.sh`.
Setting common variables in terraform.tfvars
A description of common variables, not specific to any cloud provider, are given in the table below.
| Variable Name | Required | Description |
|---|---|---|
| app_name | Y | This MUST be equal to the APP_NAME variable in env.sh. |
| helm_version | Y | Your helm version. Should be equal to the output of `helm version -c --short |
| app_name | Y | A unique identifier of your application. |
| replica_count_map | Y | This is a map that determines how many replicas and which application gets them. None of the values should be greater than replica_count, or the total number of available nodes. |
| database.flywayBaselineVersion | Y | Flyway baseline version. Set this to another value if needed. |
| database.flywayCommand | Y | Flyway command to run. Possible options are repair or migrate. |
| database.type | Y | This is the type of database that you are using. Possible options are MariaDB, Postgres, Oracle, or MSSQL. |
| database.hibernate | Y (when using Oracle or MSSQL) N otherwise | Required for Oracle and MSSQL Databases. If not using one of the specified DBs, please, ignore a variable. The complete list of docs can be found here. Example values:
|
| database.root.password | Y - in AWS Y - when using OpenIAM's MariaDB or Postgres images N - otherwise | The root password to the database. |
| database.openiam.user | Y | Username to the OpenIAM database. |
| database.openiam.password | Y | Password to the OpenIAM database. |
| database.openiam.database_name | Y | OpenIAM database name. |
| database.openiam.schema_name | Y | OpenIAM schema name. |
| database.activiti.user | Y | Username to the Activiti database. |
| database.activiti.password | Y | Password to the Activiti database. |
| database.activiti.database_name | Y | Activiti database name. |
| database.activiti.schema_name | Y | Activiti schema name. |
| redis.password | Y | Redis password. Can be left blank. |
| rabbitmq.user | Y | RabbitMQ username. |
| rabbitmq.password | Y | RabbitMQ password. |
| rabbitmq.cookie_name | Y | RabbitMQ cookie name. |
| rabbitmq.memory.memoryHighWatermark | Y | RabbitMQ memory high watermark. |
| rabbitmq.memory.request | Y | RabbitMQ requested pod memory. |
| rabbitmq.memory.limit | Y | RabbitMQ limit pod memory. |
| rabbitmq.serviceType | Y | Service Type. Set to LoadBalancer to expose externally or set to ClusterIP to set internally. |
| rabbitmq.tls.enabled | Y | Is TLS Communication Enabled for RabbitMQ? If yes, set to true. Otherwise, set to false. |
| rabbitmq.tls.failIfNoPeerCert | Y | When set to true, TLS RabbitMQ connection will be rejected if client fails to provide a certificate. |
| rabbitmq.tls.sslOptionsVerify | Y | Should peer verification be enabled? Default is verify_peer. |
| rabbitmq.jksKeyPassword | Y | Password used to generate JKS file, if RabbitMQ TLS Communication is enabled. |
| logging.level.bash | Y | Logging level of bash scripts. TRACE and DEBUG are equivalent, and both force bash to run with the -x argument. |
| logging.level.app | Y | For production use please change log level to warn or error. Debug will generate a lot of information. possible values ERROR, WARN, INFO, DEBUG, or TRACE. |
| rproxy.https.disabled | N | rProxy by default uses https. You can set this variable to 1 to disable https. |
| rproxy.https.protocol | N | SSL Protocols options. If not set, the Apache 2.4 defaults will be used. For example, you can disable everything except TLSv1.2 and allow only ciphers with high encryption like so: protocol="-ALL -TLSv1 -TLSv1.1 +TLSv1.2"cipherSuite="HIGH:!MEDIUM:!aNULL:!MD5:!RC4" |
| rproxy.https.cipherSuite | N | SSL Ciphersuite options. If not set, Apache 2.4 defaults will be used. For example, to disable everything except TLSv1.2 and allow only ciphers with high encryption use:protocol="-ALL -TLSv1 -TLSv1.1 +TLSv1.2"cipherSuite="HIGH:!MEDIUM:!aNULL:!MD5:!RC4" |
| rproxy.https.host | N | If https uses non-default(443) port, specify full https host name for redirects from http to https. For example:host=https://node1.openiam.com:8001 |
| rproxy.defaultUri | Y | For example, if user hit http://demo.openiamdemo.com/ they will be redirected to http://demo.openiamdemo.com/selfservice/ by default, instead of showing Eror 404 (not found). |
| rproxy.disableConfigure | N | This variable is set to 1 by default. It allows configuring content provider on first access. However, after that, it is possible to set it to 0 to disable configuring the content provider using the /webconsole/setup URL. |
| rproxy.verbose | N | rProxy debug options. Set any value to enable or keep empty to disable debug logging. |
| rproxy.debug.base | N | Debug option. Enables baseline debugging. |
| rproxy.debug.esb | N | Debug option. Enables debugging on calls to the ESB. |
| rproxy.debug.auth | N | Debug option. Enables debugging on authentication calls. |
| rproxy.apache.extra | N | File that is included in httpd.conf in the rProxy Docker container. Set the value to extraApache.conf or leave empty. |
| rproxy.vhost.extra | N | File that is included in httpd.conf in VirtualHost section in the rProxy Docker container. Set to extraVHost.conf or leave empty. |
| rproxy.log.error rproxy.log.access | N | By default /dev/stderr is used for OPENIAM_RPROXY_ERROR_LOG and /dev/stdout - for OPENIAM_RPROXY_ACCESS_LOG. You can change that here, for example use /dev/stdout for both error log and access log or set access log to /dev/null and log only errors. If not set, defaults used. |
| openiam.rproxy.deflate | N | Apache mod_deflate compression ratio. Values from 0 to 9. By default, is set to 6. |
| openiam.rproxy.csp | N | Content-Security-Policy headers enabled by default. To disable set to 0. |
| openiam.rproxy.cors | N | Cross-Origin Resource Sharing headers enabled by default. To disable set to 0. |
| autodeploy.openiam | N | If set to true, the OpenIAM stack will autodeploy on each terraform run. |
| autodeploy.rproxy | N | If set to true, the OpenIAM reverse proxy stack will autodeploy on each terraform run. |
| autodeploy.vault | N | If set true, the OpenIAM vault stack will autodeploy on each terraform run. |
| vault.cert.country | N | Vault Certificate Country Code. Ignore this variable, if you are using a custom vault certificate, as specified in the parent file. |
| vault.cert.state | N | Vault Certificate Country State. Ignore this variable, if you are using a custom vault certificate, as specified in the parent file. |
| vault.cert.locality | N | Vault Certificate Locality. Ignore this variable, if you are using a custom vault certificate, as specified in the parent file. |
| vault.cert.organization | N | Vault Certificate Organization. Ignore this variable, if you are using a custom vault certificate, as specified in the parent file. |
| vault.cert.organizationunit | N | Vault Certificate Organiztion Unit. Ignore this variable, if you are using a custom vault certificate, as specified in the parent file. |
| vault.vaultKeyPassword | Y | Password used to generate the vault .jks certificate. Ensure to use a strong password. |
| vault.secrets.javaKeystorePassword | Y | Java keystore password. Ensure to use a strong password. |
| vault.secrets.jks.password | Y | OpenIAM JKS Encryption Password. Ensure to use a strong password. |
| vault.secrets.jks.keyPassword | Y | OpenIAM JKS Key Password. Ensure to use a strong password. |
| vault.secrets.jks.cookieKeyPassword | Y | OpenIAM Cookie Key Password. Ensure to use a strong password. |
| vault.secrets.jks.commonKeyPassword | Y | OpenIAM Common Key Password. Ensure to use a strong password. |
| vault.replicas | Y | The number of vault and consul replicas. |
| vault.consul.storage | Y | The amount of storage to provision to Consul PVC. |
Setting the Cloud Provider
Open the main.tf file and change the following lines.
If using Google Kubernetes Engine
source = "./modules/core/gke"If using AWS
source = "./modules/core/aws"If deploying in-house
source = "./modules/core/helm"If using Azure
source = "./modules/core/azure"
Set variables specific to your cloud provider
Each cloud provider has its own specific set of required and optional variables. Follow the guide lines below based on your cloud provider.
Deploying
To deploy, run the following commands from the root folder of this project. It may take a while for all services to be created and deployed.
terraform initterraform planterraform apply # enter 'yes' when asked to do so
Note: Our terraform scripts will change your ~/.kube/config file.
Also note that if you are using AWS, you may have to run the above command twice.
Also note that if you are using AWS, you may have to run the above command twice.
Destroying
Each cloud environment has its own peculiarities (i.e. bugs) when destroying infrastructure. Destroy your infrastructure based on your cloud provider:
Managing state
Terraform stores state in local files, as indicated below.
terraform.tfstate*
In addition, running against AWS and GKE modifies your ~/.kube/config file.
When switching environments, you MUST save these files off, so that you can return to previous environments.
Migration guide
Versions pre-4.2.1 to 4.2.1
We've updated our vault datastore in v4.2.1. To migrate, follow the steps below.
- Deploy with the
vault.migrateterraform variable set totrue. - Wait for all pods to come up.
- Redeploy with the
vault.migrateterraform variable set tofalse. - Wait for all pods to come up.