Helm Chart core-cacheservice

This Helm Chart deploys Cache service core in a kubernetes cluster.

Introduction

This Chart includes the following components:

• Cache service application container to deploy in a kubernetes cluster.

Requirements

Requires Kubernetes v1.19+

Dependencies

This section will provide details about specific requirements in addition to this Helm Chart.

Pushing to registry

From wihtin ${PROJECT_DIR}/helm/core-cacheservice directory:

helm repo add ox-documents-registry https://registry.open-xchange.com/chartrepo/documents
helm repo update
helm push . ox-documents-registry

Test installation

Run a test against a cluster deployment:

helm repo add ox-documents-registry https://registry.open-xchange.com/chartrepo/documents
helm repo update
helm install --dry-run --debug --generate-name --version [VERSION] ox-documents-registry/core-cacheservice

Installing the chart

Install the Chart with the release name 'alice':

helm repo add ox-documents-registry https://registry.open-xchange.com/chartrepo/documents
helm repo update
helm install alice --version [VERSION] ox-documents-registry/core-cacheservice [-f path/to/values_with_credentials.yaml]

Configuration

Using AWS IAM for S3 object stores

By default an S3 object store authenticates with the statically configured accessKey and secretKey. Setting credentialsSource to iam instead makes the service resolve credentials through the AWS default credentials chain at runtime, in which case accessKey and secretKey are not needed and may be omitted:

cacheService:
  s3ObjectStores:
    - id: 1
      endpoint: "https://s3.eu-central-1.amazonaws.com"
      region: "eu-central-1"
      bucketName: "cacheservice"
      credentialsSource: "iam"

The credentials chain is evaluated in this order: JVM system properties, the AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY environment variables, a web identity token file (EKS IRSA), the AWS profile file, container credentials (ECS task roles and EKS Pod Identity) and finally the EC2 instance profile. Which of these applies depends on where the service runs, so nothing beyond credentialsSource: "iam" has to be configured in the chart for plain EC2 deployments.

On Kubernetes the pods have to be associated with an AWS IAM role, which requires a ServiceAccount. If the deployment does not already provide one, this chart can create it:

serviceAccount:
  create: true
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/core-cacheservice

To use an already existing ServiceAccount instead, set serviceAccount.create to false and serviceAccount.name to its name. While the serviceAccount value is left unset entirely, the pods keep using the namespace default ServiceAccount and no ServiceAccount is created.

The IAM role needs s3:ListBucket on the bucket itself plus s3:GetObject, s3:PutObject and s3:DeleteObject on its contents. Add s3:CreateBucket as well if the bucket should be created automatically on service startup, otherwise create it beforehand. Note that s3:ListBucket is mandatory even for an existing bucket, since the service verifies the bucket on startup and a missing permission makes that check fail rather than fall through.

Configuration of service properties via existing secret

In most cases, like with this service, the Helm stack chart provided values for a service are transformed into a ConfigMap properties file created during the Helm stackchart update/install step for a deployment. These config values are then used by the service container/pod during startup. Although this approach covers all relevant config properties for the service, it is often desirable for the admin to specify all or just some of the service config properties via a kubernetes secret for e.g. security reasons.

Note: Any credentials set directly via Helm values (e.g. cacheService.mysql.auth.password, basicAuth.password, cacheService.s3ObjectStores[].secretKey) end up in the plaintext ConfigMap described above, which is readable by anyone with get configmaps access in the namespace. For production deployments, use existingPropertiesSecret below to keep credentials in a Secret instead.

To provide a way to use service config values from an existing secret within the current deployment namespace, the service Helm chart contains a property to specify the name of an existing secret within the deployment namespace: .Values.existingPropertiesSecret. Service properties (key/value pairs) set within this secret always have precedence over service properties contained within the Helm chart created ConfigMap property values.

Documentation for the service-specific configuration values can be found at this configuration values location.

Since authorization data is most prone to security attacks, the following example will concentrate on these properties only, although all other service properties can be set via a deployed secret this way as well:

• HTTP API BasicAuth properties (com.openexchange.cacheservice.basicAuth.user, com.openexchange.cacheservice.basicAuth.password)
• DB authorization properties (com.openexchange.cacheservice.database.user, com.openexchange.cacheservice.database.password, com.openexchange.cacheservice.database.rootPassword)
• S3 authorization properties (com.openexchange.cacheservice.objectstore.s3.1.accessKey, com.openexchange.cacheservice.objectstore.s3.1.secretKey)

Example steps to provide a service config properties/values secret to be used by the deployed service

Step 1

First of all, a secret containing all required service config property keys and values needs to be created (current filename is ./myCacheServiceSecret.yaml) Please note that all config values need to be set as Base64 encoded values. All my* names and values need to be adjusted according to the admins' requirements.

apiVersion: v1
kind: Secret
metadata:
  name: my-cacheservice-secret
type: Opaque
data:
  com.openexchange.cacheservice.basicAuth.user: bXlCYXNpY0F1dGhVc2VyCg==  # Base64 encoded value of `myBasicAuthUser`
  com.openexchange.cacheservice.basicAuth.password: bXlCYXNpY0F1dGhQYXNzd29yZAo=  # Base64 encoded value of `myBasicAuthPassword`
  com.openexchange.cacheservice.database.user: bXlEQlVzZXIK  # Base64 encoded value of `myDBUser`
  com.openexchange.cacheservice.database.password: bXlEQlBhc3N3b3JkCg==  # Base64 encoded value of `myDBPassword`
  com.openexchange.cacheservice.database.rootPassword: bXlEQlJvb3RQYXNzd29yZAo=  # Base64 encoded value of `myDBRootPassword`
  com.openexchange.cacheservice.objectstore.s3.1.accessKey: bXlTM0FjY2Vzc0tleQo=  # Base64 encoded value of `myS3AccessKey`
  com.openexchange.cacheservice.objectstore.s3.1.secretKey: bXlTM1NlY3JldEtleQo=  # Base64 encoded value of `myS3SecretKey`

Step 2

After preparing all config values within the secret definition, the secret itself needs to be deployed or updated to the deployment namespace.

kubectl replace --force=true --namespace=myNamespace --filename=./myCacheServiceSecret.yaml

Step 3

After the property secret has been deployed to the cluster namespace the admin needs to adjust the service .Values.existingPropertiesSecret stackchart value for the service.

core-cacheservice:
  existingPropertiesSecret: my-cacheservice-secret

Step 4

The stackchart with the set Helm chart service value .Values.existingPropertiesSecret name needs to be installed or updated via usual deployment mechanisms. After the deployment has been finished, the service itself preferably uses the service key/value properties from the secret. If a secret has already been deployed and secret values need changes, the secret itself needs to be redeployed to be effective. Afterward the service itself needs to be restarted as well to acknowledge the new secret properties key/value pairs.