Skip to content

Getting started

Jump to bottom
SniXosha edited this page Sep 30, 2020 · 1 revision

Requirements

  • MacOS/Linux
  • JDK 11+
  • oc (OpenShift cli)

Building first Microconfig repository

It's highly recommended to get familiar with microconfig first.

Example osdf repository is here.

In this tutorial we will describe repo structure and some key components

Environments

To start, there are two environments - dev and prod. Their descriptions are located in repo/envs folder, both are derived from fictional base env with the list of all our components.

Components

All microconfig components are located in components folder, every folder (and all sub-folders) inside 'components' directory is a valid component so you are free to choose how to structure your configs

Apps

In this example, we have three apps: frontend, backend and auth.

Components that will represent these apps are located in components/apps dir, and we also listed them in our base.yaml environment description:

main: # group name
  components:
    - backend
    - frontend
    - auth

After microconfig build, our app components must comply with osdf requirements:

  • component must have resources sub-directory with kubernetes resources inside
  • component must have deploy.yaml with required app.version and config.version properties

To create deploy.yaml file, we can store our configs in .deploy files.

Backend app

Let's try to make sense out of backend component

service.deploy file has main configuration properties

#include k8s-service # use k8s-service component as a template

app.version: 1.1 # set app version to 1.1

osdf.configmap.backend: # tell osdf to create configmap from application.yaml file
  name: backend
  files:
    - application.yaml

k8s-service is a helper component which has templates for Deployment and Service resources with placeholders and other configuration. This is needed to:

  • avoid copy paste of nearly identical kubernetes resources across our apps.
  • share common configuration (versions in our example)

k8s-service/template.deploy

#include versions

mc.template.service: ${k8s-service@configDir}/deployment-and-service.yaml -> resources/deployment-and-service.yaml # generate template

image.version: ${this@app.version} # set image.version (used as placeholder in Deployment) to match app.version
server.port: ${app::this@server.port:8080} # set server.port to match port defined in application configs (common case in spring apps)

version component has required app.version and config.version properties.

app.version: ${process::versions@project.version}
config.version: ${process::versions@config.version}

Note that we set them using properties from config-version.proc and project-version.proc. This is needed to be able dynamically change image version (and config version if needed) using osdf:

  • deployment has ${this@image.version} placeholder
  • image.version equals app.version
  • app.version equals project.version (from project-version.proc)
  • project.version in project-version.proc is modified dynamically by osdf

Conditional template generation

Suppose that we want to have Route resource in dev environment for our backend app for debugging purposes (we don't want to have it in production environment, we will only expose fronend app). We can do that by creating *.dev.deploy* file with required instructions. In this example, this is done in route.dev.deploy file.

Overrides

All our apps use k8s-service as template, but each one of them has some service specific overrides or additions. For example:

  • auth generates logback.xml template
  • backend has fixed app.version property
  • frontend has different server.port and has route inclusion for all envs

Using microconfig, it's possible to create complex yet readable configuration for microservices without having to copypaste common properties across apps and environments.

Setting cluster properties

components/system/k8s-cluster component contains cluster properties:

  • project - kubernetes namespace
  • cluster.url.api - api url of your OpenShift cluster

Note that we have defined separate properties for each env

Deploying using osdf

Now let's try to deploy these apps using osdf. Firstly, we have to initialize osdf with our repository, OpenShift credentials, environment and versions.

~ osdf init local-configs -p /path/to/configs -v tutorial # initialize from local-configs, set config-version to 'tutorial' 
Environment is not specified
~ osdf env dev # set dev environment
...microconfig output...
~ osdf versions -pv 1.0 # set `app.version` to 1.0
...microconfig output...
~ osdf init openshift -c user:pass # set openshift credentials

And deploy all apps

~ osdf deploy # deploys all apps by default
Deploying: frontend backend auth
Deploying group - [frontend, backend, auth]
frontend OK
backend OK
auth OK
OK

Check their status using osdf status command:

~ osdf status
COMPONENT    VERSION    CONFIGS    STATUS       REPLICAS
frontend     1.0        tutorial   READY        1/1
backend      1.1        tutorial   READY        1/1
auth         1.0        tutorial   READY        1/1

Docs

Full docs are available here - https://github.com/microconfig/osdf/wiki/Docs

Clone this wiki locally