Platform

• 1: Requirements
• 2: Deploy an application
• 3: Update configurations
• 4: Update secrets
• 5: FAQ

1 - Requirements

To be compatible with the environment of the Dolittle platform, there are certain requirements we impose on your microservices. If they are not met, your application might behave unexpectedly - or in the worst case - not work at all. The following list of requirements is subject to change, but we will always notify you when you have an application running in our platform before making any changes.

1. Your application must use the resource system

To ensure data privacy, security and proper segregation of your tenant’s data, our platform has a resource management system. This system controls access and connection settings for resources on a per request basis and will provide your microservice with the necessary information for accessing these resources programmatically. The connection information will not be the same as when developing locally, so you must not embed connection settings in your code.

This requirement applies to read and write data to databases or files, or while making API-calls to services, both to internal resources provided by the Dolittle platform and external 3rd party services.

2. All your applications external endpoints must be configured and exposed through the platform

For the resource management system to work, and to protect your application and users from data leakage, we encrypt and authenticate all interactions with your application through the platform. This means that your microservices will be completely isolated by default, and all endpoints that should be accessible outside our platform needs to be exposed explicitly and configured with appropriate encryption and authentication schemes.

To enable same-origin authentication flows and adhere to internet best practices, the platform will take control of a set of URIs for the hostnames you have allocated to your application. The following paths and any sub-path of these (in any form of capitalisation) are reserved for the platform:

• /.well-known
• /robots.txt
• /sitemap
• /api/Dolittle
• /Dolittle

3. Your microservices must be stateless, scalable and probeable

To allow for efficient hosting of your application, we have to able to upgrade, re-start, move and scale your microservices to handle the load and perform necessary security upgrades. This means that you must not rely on any in-memory state for anything apart from the per-transaction state, and you must not rely on there being a single instance of your microservices at any point in time.

To ensure that your microservices are healthy and ready to perform work, your microservices must expose both liveness and readiness probes. The microservice should respond to the liveness probe whenever it has successfully started and is in a functional state, and should respond to the readiness probe whenever it is free to handle incoming requests from users.

4. Your application must adhere to semantic versioning of your microservices

We rely on semantic versioning to properly track changes of your microservices (from an operational aspect) and to decide on the correct course of action when new versions of your microservices are built. Minor or patch increments will result in automatic upgrades of your running microservices without any human interaction, while major increments require manual approval and potential updates of configuration or data structures. This means that you must increment the major number when making changes to your microservices that require changes in the platform for your application to work properly.

5. Your frontend must be a static single-page application

To ensure that any user-facing frontend is served quickly and with minimal data-usage, we serve your frontend using separate servers with appropriate caching, compression and CDN strategies. This means that your frontend must be built as a single-page application to static HTML, CSS and js files. These files must be built and versioned alongside your backend microservices to ensure that the frontend and backend versions are aligned and function properly.

2 - Deploy an application

Prerequisites

Familiar with the following:

• Docker containers
• Kubernetes
• Microsoft Azure

Recommendation

For users on Windows OS, we recommend that you use WSL/Ubuntu as your shell/terminal instead of CMD/Powershell.

• Install WSL on Windows 10

Installation

Install the following software:

• Docker Desktop
• Kubectl
• Azure CLI

Configuration

After an environment has been provisioned for you in the Dolittle PaaS, you will receive these details to use with the deployment commands in the following sections:

Subscription ID
Resource Group
Cluster Name
Application Namespace
ACR Registry
Image Repository
Deployment Name
Application URL

Setup

All commands are meant to be run in a terminal (Shell)

AZURE

Login to Azure:

az login

AKS - Azure Container Service

Get credentials from Dolittle’s AKS cluster

az aks get-credentials -g <Resource Group> -n <Cluster Name> --subscription <Subscription ID>

ACR - Azure Container Registry

Get credentials to Azure Container Registry

az acr login -n <ACR Registry> --subscription <Subscription ID>

Deployment

To deploy a new version of your application, follow these steps. For use semantic versioning, e.g. “1.0.0”.

Docker

Build your image

docker build -t <Image Repository>:<Tag> .

Push the image to ACR

docker push <Image Repository>:<Tag>

Kubernetes

Patch the Kubernetes deployment to run your new version

kubectl patch --namespace <Application Namespace> deployment <Deployment Name> -p '{"spec": { "template": { "spec": { "containers": [{ "name":"head", "image": "<Image Repository>:<Tag>"}] }}}}'

Debugging

kubectl commands:

Show the status of your application pods

kubectl -n <Application Namespace> get pods

Show deployed version of your application

kubectl -n <Application Namespace> get deployment -o wide

Show the logs of the last deployed version of the application

kubectl -n <Application Namespace> logs deployments/<Deployment Name>

Logs for the application, last 100 lines

kubectl -n <Application Namespace> logs deployments/<Deployment Name> --tail=100

3 - Update configurations

Prerequisites

Familiar with the following:

• Kubernetes
• yaml

Recommendation

For users on Windows OS, we recommend that you use WSL/Ubuntu as your shell/terminal instead of CMD/Poweshell.

• Install WSL on Windows 10

Installation

Install the following software:

• Kubectl

Configuration

After an environment has been provisioned for you in the Dolittle PaaS, you will receive a yaml file per environment. The files will be similar to this:

---
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: application-namespace
  name: app-dev-ms-env-variables
  labels:
    tenant: Customer
    application: App-Dev
    microservice: MS-A
data:
  OPENID_AUTHORITY: "yourapp.auth0.com"
  OPENID_CLIENT: "client-id"
  OPENID_CLIENTSECRET: "client-secret"

---
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: application-namespace
  name: app-dev-ms-config-files
  labels:
    tenant: Customer
    application: App-Dev
    microservice: MS-A
data:
  myapp.json: |
    {
       "somekey": "somevalue"
    }    

The files represent configmap resources in Kubernetes. We recommend that you store the files in a version control system(VCS) of your choice.

Purpose

Each yaml file consists of 2 configmaps per micro-service:

• app-dev-ms-env-variables: This configmap is for your environmental variables that will be passed on to the container at start up.
• app-dev-ms-config-files: This configmap is for add/override files. The default mount point is app/data

---
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: application-namespace
  name: app-dev-ms-env-variables
  labels:
    tenant: Customer
    application: App-Dev
    microservice: MS-A
data:

You may alter the content under data:

  OPENID_AUTHORITY: "yourapp.auth0.com"
  OPENID_CLIENT: "client-id"
  OPENID_CLIENTSECRET: "client-secret"
  connectionstring__myconnection: "strings"

Alter existing or add new key/value pairs.

myapp.json: |
    {
       "somekey": "somevalue"
    }    

customSetting.json: |
  {
    "settings": {
       "connection":"connectionstring"
     }
  }  

Alter existing or add new JSON data that will be linked to a specific file that will be available at runtime under app/data/

Setup

You need to setup your AKS credentials.

Update configurations

To update the configurations:

kubectl apply -f <filename>

You must be in the directory of the yaml file before running the command.

To update/add a single key in the config:

kubectl patch -n <Application Namespace> configmap <Configmap Name>  -p '{"data":{"my-key":"value that i want"}}'

To remove a single key from the configuration:

kubectl patch -n <Application Namespace> configmap <Configmap Name>  -p '{"data":{"my-key":null}}'

See configurations

JSON output

kubectl get -n <Application Namespace> configmap <Configmap Name> -o json

YAML output:

kubectl get -n <Application Namespace> configmap <Configmap Name> -o yaml

For an advanced print out, you need a tool called jq for parsing

kubectl get -n configmap -o json | jq -j ‘.data | to_entries | .[] | “(.key): (.value)\n”’

4 - Update secrets

Prerequisites

Familiar with the following:

• Kubernetes
• yaml

Recommendation

For users on Windows OS, we recommend that you use WSL/Ubuntu as your shell/terminal instead of CMD/Poweshell.

• Install WSL on Windows 10

Installation

Install the following software:

• Kubectl

Secrets

After an environment has been provisioned for you in the Dolittle PaaS, you will receive a yaml file per environment. The files will be similar to this:

---
apiVersion: v1
kind: Secret
metadata:
  namespace: application-namespace
  name: apps-dev-ms-secret-env-variables
  labels:
    tenant: Customer
    application: App-Dev
    microservice: MS-A
type: Opaque
data:
   OPENID_SECRET: b3BlbiBpZCBzZWNyZXQ=

The files represent the Secrets -resource in Kubernetes. We recommend that you store the files in a version control system(VCS) of your choice.

Purpose

Each yaml file consists of a secret per micro-service:

• app-dev-ms-secret-env-variables: This secret is for your environmental variables that will be passed on to the container at start up. One important thing to remember is that the values have to be encoded using base64.

---
apiVersion: v1
kind: Secret
metadata:
  namespace: application-namespace
  name: apps-dev-ms-secret-env-variables
  labels:
    tenant: Customer
    application: App-Dev
    microservice: MS-A
type: Opaque
data:

You may alter existing or add new key/value pairs.

  OPENID_SECRET: b3BlbiBpZCBzZWNyZXQ=
  DB_PASSWORD: c29tZSBwYXNzd29yZA==

Setup

You need to setup your AKS credentials.

Encode secrets

To encode values:

echo -n "my super secret pwd" | base64 -w0

The above command will give you:

bXkgc3VwZXIgc2VjcmV0IHB3ZA==

The value can then be added to the secrets:

MY_SECRET: bXkgc3VwZXIgc2VjcmV0IHB3ZA==

Update secrets

To update the secrets:

kubectl apply -f <filename>

You must be in the directory of the yaml file before running the command.

To update/add a single key in the secrets:

kubectl patch -n <Application Namespace> secret <Secrets Name>  -p '{"data":{"my-key":"value that i want encoded using base64"}}'

To remove a single key from the configuration:

kubectl patch -n <Application Namespace> secret <Secrets Name>  -p '{"data":{"my-key":null}}'

See secrets

JSON output:

kubectl get -n <Application Namespace> secret <Secrets Name> -o json

YAML output:

kubectl get -n <Application Namespace> secret <Secrets Name> -o yaml

For an advanced print out, you need a tool called jq for parsing the JSON in you shell:

kubectl get -n <Application Namespace> secret <Secrets Name> -o json | jq -j '.data | to_entries | .[] | "\(.key): \(.value)\n"'

5 - FAQ

Can I login without allowing cookies?

If you’re getting strange results with logon through Sentry or another OIDC service - check that you’re allowing cookies for the domains!

Without cookies you cannot logon - at all. Sorry!