Kubernetes

Kubernetes, also known as K8s, is an open-source system for automating the deployment, scaling, and management of containerized applications.

Kubernetes is open-source and adaptable to a number of cloud providers including Amazon, Google, Azure and others. It allows you to express your infrastructure configuration in such a way as to take advantage of on-premises and a diversity of hybrid and public cloud infrastructures.

For information on Kubernetes, please visit https://kubernetes.io.

Gitana SDK

The code and configuration provided here references the samples provided in the Gitana SDK. We recommend that you pull down this code and consulting the files there for reference:

Gitana SDK - Kubernetes Examples for Gitana 3.2

Infrastructure

In this article, we'll walk through the configuration of Gitana within a barebones Kubernetes environment. This example uses Kubernetes yaml files directly and does not make sure of a build system (such as Helm). This is not intended as a best-practice example but rather as a reference that may help with your own implementations.

In addition to setting up the Gitana API and UI, we will also set up containers for:

  • MongoDB
  • Elastic Search
  • Active MQ

Gitana works natively with all of these. This guide provides sample configurations to integrate with both.

Getting Started

We recommend using the Gitana Tools library to auto-generate a base set of configuration files for use in your container framework. This is a good starting point no matter whether you're using Kubernetes, ECS or any other framework.

To begin, open up a terminal session and go into an empty directory.

Then run the following for your specific version of Gitana:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.85 generate-certificate --name properties
docker run -v .:/data public.ecr.aws/gitana/admin:3.2.85 generate-root-properties --cert config/keys/properties.crt

This will generate the following

config/root.properties                          (encrypted root properties)
config/keys/properties.key                      (private key file)
config/keys/properties.pem                      (public key file)
config/keys/properties.crt                      (certificate)

The root.properties file holds the unique security tokens for your cluster. These tokens are encrypted using your properties.crt certificate / public key.

You should now generate your "admin" password. This can be appended to your root properties.

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.85 set-property --file config/root.properties --cert config/keys/properties.crt --property admin.password --value admin

Make sure that you change the value of admin to something secure.

You should then also create your API extension files:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.85 generate-config

This will generate:

config/api/setup.sh
config/api/classes/container.properties
config/api/classes/log4j2-container.xml
config/api/classes/gitana-container-context.xml

Configure Kubernetes

Kubernetes Secret

We begin by creating a gitana-env Kubernetes Secret that stores environment variables that get passed to the Gitana API container:

kubectl create secret generic gitana-env \
--from-file=gitana.rootProperties.value=./gitana/root.properties \
--from-file=gitana.propertiesPrivateKey.value=./gitana/properties.key \
--from-file=gitana.license.value=./gitana/cloudcms_unlimited_19_jul_2015.lic

If we have any API configuration file extensions, those can be loaded into a gitana-files secret:

kubectl create secret generic gitana-files \
--from-file=./gitana/api/container.properties \
--from-file=./gitana/api/gitana-container-context.xml \
--from-file=./gitana/api/log4j2-container.xml \
--from-file=./gitana/api/setup.sh

Cluster Configuration

Provide a name and password for your Gitana cluster. Also, enable AWS. Provide an AWS tag key/value that is applied to EC2 instances to support EC2 discovery.

Make the following changes to api/classes/container.properties:

cluster.group.name=mycluster
cluster.group.password=mycluster
cluster.port=5800

Enable AWS

cluster.aws.enabled=true
cluster.aws.tag.key=mycluster
cluster.aws.tag.value=mycluster-member

Gitana Config Map

The files from your ./gitana directory are packaged up into a Kubernetes Config Map. The config map is then mounted to the root /gitana path within your containers.

Starting / Stopping

Within your terminal window, to start things, run:

sh start.sh

To stop things, you can run:

sh stop.sh

INCLUDE_2:

Additional Configuration Notes

Read an encrypted value from root.properties

To get an encrypted property from your root.properties file, you can run:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.84 get-property --privateKey properties.key --file root.properties --property $PROPERTY

Where $PROPERTY is the name of the property to retrieve.

If privateKey is supplied, the value will be decrypted using the private key.
Otherwise, it will be retrieved as the raw stored value.

Set an encrypted value in root.properties

To set an encrypted property into your root.properties file, you can run:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.84 set-property --cert properties.crt --file root.properties --property $PROPERTY --value $VALUE

Where $PROPERTY is the name of the property to set and $VALUE is the value to be set.

If cert is supplied, the value will be encrypted using the public key. Otherwise, the raw unencrypted value will be stored.

Secrets vs Environment Variables vs Files

Depending on the container framework you use, you may wish to leverage Secrets to store private information such as the generated private key or Gitana license file. Most container frameworks (such as ECS or Kubernetes) let you create these secrets and then mount them into your running containers either as environment variables or files.

Gitana can pick up these from either location.

Gitana License

You can directly specify the value for the Gitana License either as an environment variable or via a file located on a volume on disk.

  • Use GITANA_LICENSE to specify a value directly
  • Use GITANA_LICENSE_PATH to specify a location on a container-attached volume where the license file exists

Root Properties

You can directly specify the value of the root.properties file either as an environment variable or via a file located on a volume on disk.

  • Use GITANA_ROOT_PROPERTIES to specify a value directly
  • Use GITANA_ROOT_PROPERTIES_PATH to specify a location on a container-attached volume where the root.properties file may be found.

For the latter, the default is assumed to be /gitana/root.properties.

Properties Private Key

You can directly specify the value of the Properties Private Key file either as an environment variable or via a file located on a volume on disk.

  • Use GITANA_PROPERTIES_PRIVATE_KEY to specify a value directly
  • Use GITANA_PROPERTIES_PRIVATE_KEY_PATH to specify a location on a container-attached volume where the properties.key file may be found.

For the latter, the default is assumed to be /gitana/keys/properties.key.