Deploying OpenIAM with Terraform

This guide describes how to deploy OpenIAM with Helm and Terraform.

Prerequisites

  1. Install Terraform. If it is not already installed (visit terraform.io for other distributions).

  2. Modify terraform.tfvars. Set the value of the "app_name" variable IN terraform.tfvars to be the same as the APP_NAME variable in env.sh

Set common variables in terraform.tfvars

Below there is a description of common variables, not specific to any cloud provider.

Variable NameRequiredDescription
app_nameYThis MUST be equal to the APP_NAME variable in env.sh
helm_versionYYour helm version. Should be equal to the output of `helm version -c --short
app_nameYA unique identifier of your application
replica_count_mapYThis is a map that determines which app get how many replicas. None of the values should be greater than replica_count, or the total number of available nodes
database.flywayBaselineVersionYFlyway baseline version. set this to another value if you're
database.flywayCommandYFlyway command to run. repair or migrate
database.typeYThis is the type of database that you are using. Can be one of 'MariaDB', 'Postgres', 'Oracle', or 'MSSQL'
database.hibernateY (when using Oracle or MSSQL)required for Oracle and MSSQL. Ignored otherwise
N otherwiseFor a complete list, see https://docs.jboss.org/hibernate/orm/3.5/javadocs/org/hibernate/dialect/package-summary.html
Example values:
org.hibernate.dialect.Oracle10gDialect ( the most common value for Oracle)
org.hibernate.dialect.SQLServer2008Dialect (the most common value for MSSQL)
database.root.passwordY - in AWSThe root password to the database
Y - when using OpenIAM's Mariadb
or Postgres images
N - otherwise
database.openiam.userYUsername to the Openiam database
database.openiam.passwordYPassword to the Openiam database
database.openiam.database_nameYOpeniam database name
database.openiam.schema_nameYOpeniam schema name
database.activiti.userYUsername to the Activiti database
database.activiti.passwordYPassword to the Activiti database
database.activiti.database_nameYActiviti database name
database.activiti.schema_nameYActiviti schema name
redis.passwordYRedis password. Can be blank
rabbitmq.userYRabbitMQ Username
rabbitmq.passwordYRabbitMQ Password
rabbitmq.cookie_nameYRabbitMQ Cookie Name
rabbitmq.memory.memoryHighWatermarkYRabbitMQ Memory High Watermark
rabbitmq.memory.requestYRabbitMQ Requested Pod Memory
rabbitmq.memory.limitYRabbitMQ Limit Pod Memory
rabbitmq.serviceTypeYService Type. Set to LoadBalancer to expose externally, or set to ClusterIP to set internally.
rabbitmq.tls.enabledYIs TLS Communication Enabled for RabbitMQ? If yes, set to true. Otherwise, set to false
rabbitmq.tls.failIfNoPeerCertYWhen set to true, TLS RabbitMQ connection will be rejected if client fails to provide a certificate
rabbitmq.tls.sslOptionsVerifyYShould peer verification be enabled? Default is verify_peer
rabbitmq.jksKeyPasswordYPassword used to generate JKS file, if RabbitMQ TLS Communication is enabled
logging.level.bashYLogging level of bash scripts. TRACE and DEBUG are equivalent, and both force bash to run with the '-x' argument
logging.level.appYfor 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.disabledNrproxy by default uses https. you can set this to 1 to disable https
rproxy.https.protocolNSSL Protocols options. if not set, apache 2.4 defaults will be used.
For Example: disable everything except TLSv1.2 and allow only ciphers with high encryption:
protocol="-ALL -TLSv1 -TLSv1.1 +TLSv1.2"
cipherSuite="HIGH:!MEDIUM:!aNULL:!MD5:!RC4"
rproxy.https.cipherSuiteNSSL Ciphersuite options. if not set, apache 2.4 defaults will be used.
For Example: disable everything except TLSv1.2 and allow only ciphers with high encryption:
protocol="-ALL -TLSv1 -TLSv1.1 +TLSv1.2"
cipherSuite="HIGH:!MEDIUM:!aNULL:!MD5:!RC4"
rproxy.https.hostNif 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.defaultUriYIf user hit for example: http://demo.openiamdemo.com/ redirect him to
http://demo.openiamdemo.com/selfservice/ by default, instead of showing error 404 (not found).
rproxy.disableConfigureNthis is set to 1 by default. this allow to configure content provider on first access.
But after that, it is possible to set it to 0 to disable ability to configure content provider using the /webconsole/setup url
rproxy.verboseNrproxy debug options. set any value for enable or keep empty for disable debug logging
rproxy.debug.baseNdebug option. Enable base debugging
rproxy.debug.esbNdebug option. Enable debugging on calls to the ESB
rproxy.debug.authNdebug option. Enable debugging on authentication calls
rproxy.apache.extraNFile that is included in httpd.conf in the rproxy Docker container. Should be extraApache.conf or empty
rproxy.vhost.extraNFile that is included in httpd.conf in VirtualHost section in the rproxy Docker container. Should be extraVHost.conf or empty
rproxy.log.errorNBy default /dev/stderr used for OPENIAM_RPROXY_ERROR_LOG and
rproxy.log.accessN/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.deflateNApache mod_deflate compression ratio. Values from 0 to 9. By default is set to 6
openiam.rproxy.cspNContent-Security-Policy headers enabled by default. To disable set to '0'
openiam.rproxy.corsNCross-Origin Resource Sharing headers enabled by default. To disable set to '0'
autodeploy.openiamNif true, the openiam stack will autodeploy on each terraform run
autodeploy.rproxyNif true, the openiam reverse proxy stack will autodeploy on each terraform run
autodeploy.vaultNif true, the openiam vault stack will autodeploy on each terraform run
vault.cert.countryNVault Certificate Country Code. Ignored if you are using a custom vault certificate, as specified in the parent file.
vault.cert.stateNVault Certificate Country State. Ignored if you are using a custom vault certificate, as specified in the parent file.
vault.cert.localityNVault Certificate Locality. Ignored if you are using a custom vault certificate, as specified in the parent file.
vault.cert.organizationNVault Certificate Organiztion. Ignored if you are using a custom vault certificate, as specified in the parent file.
vault.cert.organizationunitNVault Certificate Organiztion Unit. Ignored if you are using a custom vault certificate, as specified in the parent file.
vault.vaultKeyPasswordYPassword used to generate the vault jks certificate. Use a strong password.
vault.secrets.javaKeystorePasswordYJava keystore password
vault.secrets.jks.passwordYOpenIAM JKS Encryption Password. Use a strong password.
vault.secrets.jks.keyPasswordYOpenIAM JKS Key Password. Use a strong password.
vault.secrets.jks.cookieKeyPasswordYOpenIAM Cookie Key Password. Use a strong password.
vault.secrets.jks.commonKeyPasswordYOpenIAM Common Key Password. Use a strong password.
vault.replicasYThe number of vault and consul replicas
vault.consul.storageYHow much storage to provision to Consul PVC

Set the Cloud Provider

Open the file 'main.tf' and change the following line:

  1. if using Google Kubernetes Engine:

    source = "./modules/core/gke"
  2. if using AWS:

    source = "./modules/core/aws"
  3. if deploying in-house:

    source = "./modules/core/helm"
  4. if uzing Azure:

    source = "./modules/core/azure"

Set variables specific to your cloud provider

Each cloud provider has it's own specific set of required and optional variables

Follow the guide based on your cloud provider:

  1. Google Cloud Engine
  2. Google Cloud Engine
  3. AWS
  4. Private Kuberenetes Cluster
  5. Azure

Deploying

To deploy, run the following commands from the root folder of this project. It may tak a while for all services to create and deploy

terraform init
terraform plan
terraform apply # enter 'yes' when asked to do so

Note: our terraform scripts will change your ~/.kube/config file

Also note - if using AWS, you may have to run the above command twice.

Destroying

Each cloud environment has it's own peculiarities (i.e. bugs) when destroying infrastructure.

Destroy your infrastructure based on your cloud provider:

  1. Google Cloud Engine
  2. Google Cloud Engine
  3. AWS
  4. Private Kubernetes Cluster

Managing State

Terraform stores state in local files

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

pre-4.2.1 to 4.2.1

We've updated our vault datastore in 4.2.1. To migrate, do the following:

  1. Deploy with the vault.migrate terraform variable set to true
  2. Wait for all pods to come up
  3. Redeploy with the vault.migrate terraform variable set to false
  4. Wait for all pods to come up