Deployment

All Kaa services, including IAM, are distributed as Helm charts. You can run these charts using Kubernetes.

Preparation

These steps should be done once for your entire Kaa cluster in Kubernetes.

  1. Install Kubernetes.

  2. Install Helm client.

  3. Create a Kaa license secret (remember to put in your Kaa license key file contents and password):

export HISTCONTROL=ignorespace # Prevent saving your key password in the shell history; note the leading space in the next line
 cat << EOF > /tmp/kaa-license.yaml
apiVersion: v1
data:
  file: < your license key file contents, base64-encoded >
  password: < your license key password >
kind: Secret
metadata:
  name: license
  type: Opaque
EOF
kubectl create -f /tmp/kaa-license.yaml
  1. Specify the image pull secret for the official KaaIoT docker registry. To define this secret, use your KaaID credentials:
export HISTCONTROL=ignorespace  # Prevent saving your credentials in the shell history; note the leading space in the next line
 export KAAID_EMAIL=<your KaaID email, eg. bob@example.com> KAAID_PASSWORD=<your KaaID password>
kubectl create secret docker-registry kaaid --docker-server=dev-hub.kaaiot.net --docker-username=$KAAID_EMAIL --docker-email=$KAAID_EMAIL --docker-password=$KAAID_PASSWORD
  1. Add the KaaIoT Helm repository:
helm repo add kaa-museum https://museum.kaaiot.net/

Installation

Once you have completed the preparation steps, everything is ready for deploying IAM on your Kubernetes cluster. To deploy the service, run the following command (observe the reference to the previously created license secret):

helm install --set global.license.existingSecret=license kaa-museum/iam --name kaa-iam

Check that pods are running:

kubectl get pods

Once the service initialization is complete, you should observe the output similar to the below:

NAME                                          READY   STATUS             RESTARTS   AGE
...
kaa-iam                                       1/1     Running            0          2m
...

Chart Requirements

Repository Name Version
@bitnami postgresql 10.1.1
@elastic elasticsearch 7.14.0
@kaa service-chart 0.0.36

Chart Values

Key Type Default Description
affinity object {} Schedulable node selection affinity constraints.
annotations.deployment object {} Deployment annotations.
annotations.pod object {} Pod template annotations.
config string "" Content for the service config map, automatically mounted as a config file into the pod.
elasticsearch.enabled bool true Enables Elasticsearch chart deployment.
elasticsearch.nameOverride string "iam-es" Overrides Elasticsearch chart name.
elasticsearch.password string "" Elasticsearch password.
elasticsearch.urlOverride string "" Full Elasticsearch URL. Default: http://{elasticsearch.nameOverride}-master:9200
elasticsearch.username string "" Elasticsearch username.
env object {} Defines the environment variables that Kubernetes passes to the service replica.
extraPodSpecs.automountServiceAccountToken bool false Enables service account API credentials automounting inside the pod.
fullnameOverride string "" Completely replaces the generated chart name.
global.image.pullSecrets list [] List of image pull secret names. Each must be defined as a record with the name field.
global.keycloak.backend.existingSecret string "-keycloak-backend" Keycloak backend client credentials secret with two keys: client-id and client-secret.
global.keycloak.privateUrl string "-keycloak" Keycloak private in-cluster URL.
global.keycloak.publicUrl string "-keycloak" Keycloak public URL.
global.license.existingSecret string "-kaa-license" Name of the license secret, which must contain two base64-encoded fields: file (license file contents in PKCS #12) and password.
global.monitoring.enabled bool false Enables Prometheus monitoring.
global.nats.url string "" NATS URL.
global.postgresql.existingSecret string "" Name of an existing Kubernetes secret containing PostgreSQL admin and user passwords (with postgresql-postgres-password and postgresql-password secret keys, respectively).
image.pullPolicy string "IfNotPresent" Docker image pull policy.
image.pullSecrets list [] List of image pull secret names. Each must be defined as a record with the name field. Overrides global.image.pullSecrets.
image.repository string "dev-hub.kaaiot.net/core/service//" Docker registry image URL.
image.tag string "" Docker image tag version to pull and run.
ingress.annotations string nil Ingress key-value annotations.
ingress.enabled bool false Enables Ingress.
ingress.hosts list ["chart-example.local"] A list of Ingress hosts.
ingress.paths list [] A list of paths.
ingress.tls list [] List of host and secret (with TLS private key and certificate) pairs.
metadata.component string "backend" The component within the architecture.
metadata.partOf string "kaa" The name of a higher level application this one is part of.
nameOverride string "" Overrides the name of the chart in the Chart.yaml.
nodeSelector object {} Schedulable node selection constraints.
postgresql.enabled bool true Enables PostgreSQL chart deployment.
postgresql.persistence.enabled bool true Enables Postgres persistence using PVC.
postgresql.postgresqlDatabase string "iam" Postgres database name.
postgresql.postgresqlUsername string "iam" Postgres username.
postgresql.replication.enabled bool false Enables Postgres deployment in replica mode.
postgresql.service.port int 5432 PostgreSQL port
postgresql.url string "-" PostgreSQL URL.
probes.enabled bool true Enables liveness, readiness, and startup probes for containers.
probes.liveness.initialDelaySeconds int 15 Liveness probe initial delay in seconds.
probes.liveness.periodSeconds int 15 Liveness probe frequency in seconds.
probes.readiness.initialDelaySeconds int 5 Readiness probe initial delay in seconds.
probes.readiness.periodSeconds int 15 Readiness probe frequency in seconds.
replicaCount int 1 The number of service instance replicas to run.
resources.limits.cpu int 1 Upper-bound CPU allocated to pod.
resources.limits.memory string "512Mi" Upper-bound memory allocated to pod.
resources.requests.cpu string "100m" Minimum CPU required by the pod to operate.
resources.requests.memory string "128Mi" Minimum memory required by the pod to operate.
runbookUrl string "" Runbook url prefix for default rules.
securityContext object {} Base container security context.
service.externalIPs list [] Kubernetes service external IPs that service is accessed from.
service.loadBalancerIP string "" Kubernetes service load balancer IP.
service.port int 80 Kubernetes service port.
service.type string "ClusterIP" Kubernetes service type.
terminationMessagePolicy string "FallbackToLogsOnError" Kubernetes termination message policy.
tolerations list [] Schedulable tainted node tolerations.
waitContainers.curl.image string "dev-hub.kaaiot.net/devops/docker/alpine-curl-jq/alpine-curl-jq" Docker image with cURL.
waitContainers.curl.tag string "0.0.2" Docker image tag with cURL.
waitContainers.enabled bool true Enables waiting for dependency services.
waitContainers.timeout int 300 Wait timeout for dependency services in seconds.

The keys with no description are standard Kubernetes values. Refer to the official Kubernetes documentation for more information on these.

Environment variables

The table below summarizes the variables supported by the IAM Docker image and provides default values along with descriptions.

Variable name Default value Description
APP_CONFIG_PATH "/srv/iam/service-config.yml" Path to the service configuration YAML file inside container. In case of running in Kubernetes, consider using K8s Volumes for externalization.
NATS_URLS "nats://nats:4222" NATS connection URLs. May include connection credentials, e.g. "nats://derek:pass@localhost:4222".
KAA_ELASTICSEARCH_URL "" Elasticsearch connection URL.
KAA_ELASTICSEARCH_USERNAME "" Elasticsearch connection username.
KAA_ELASTICSEARCH_PASSWORD "" Elasticsearch connection password.
KAA_POSTGRESQL_HOST "127.0.0.1" PostgreSQL connection host.
KAA_POSTGRESQL_PORT 5432 PostgreSQL connection port.
KAA_POSTGRESQL_USERNAME "iam" PostgreSQL connection username.
KAA_POSTGRESQL_PASSWORD "iam" PostgreSQL connection password.
KAA_POSTGRESQL_DATABASE "iam" PostgreSQL connection database.
KAA_POSTGRESQL_SSL_MODE "disable" PostgreSQL connection SSL mode ("disable", "require", "verify-ca", "verify-full").
KAA_POSTGRESQL_MAX_OPEN_CONNECTIONS 100 Maximum number of open connections to PostgreSQL.
KAA_SECURITY_ENABLED false Enables authentication and authorization on REST API endpoints (inbound and outbound API calls).
KAA_SECURITY_MULTITENANCY_ENABLED false Enables multitenancy via integration with the Kaa Tenant Manager. Only effective when kaa.security.enabled is set to true..
KAA_SECURITY_ISSUER_PUBLIC_URL   OAuth 2.0 issuer public URL for the system tenant (“kaa”).
KAA_SECURITY_ISSUER_PRIVATE_URL   OAuth 2.0 issuer private URL for the system tenant (“kaa”).
KAA_SECURITY_CLIENT_ID   Client ID for making requests in the system tenant scope.
KAA_SECURITY_CLIENT_SECRET   Client secret for making requests in the system tenant scope.
KAA_SECURITY_MULTITENANCY_TENANT_MANAGER_URL "http://tenant-manager" URL of the Kaa Tenant Manager that provides security configurations for tenants.
KAA_LICENSE_CERT_PATH "/run/license/license.p12" Path to the Kaa platform license certificate file in PKCS #12 format.
KAA_LICENSE_CERT_PASSWORD   License certificate password. Required.
SERVICE_DEBUG false Enables debug level logging.
SERVER_PORT 8090 Server port to expose application.

Some of the listed above settings can also be controlled via the configuration options. When set, environment variables take precedence over corresponding configuration file settings.