Skip to content

Configuration

Jump to bottom
Vincent Composieux edited this page Oct 30, 2020 · 3 revisions

Configuration is the most important part of Monday: you have to define your projects and its dependencies (local and/or forwarded apps) into a YAML format.

By default, Monday will read the monday.yaml configuration file, but you can also split your configuration files using this pattern: monday.*.yaml, so you can for instance define:

  • monday.local.yaml
  • monday.forward.yaml
  • monday.project.yaml

It could ease the read of configuration files when working on large projects.

Even if a configuration example file is available here, we will try to decouple it in multiple parts to give you a better understand.

Configure local applications

First, you will define the local applications you want to work on:

<: &graphql-local
  name: graphql
  path: github.com/eko/graphql # Will find in GOPATH (as executable is "go")
  watch: true # Default: false (do not watch directory)
  hostname: graphql.svc.local # Optional, in case you want to map a specific hostname with a single IP address
  setup: # Optional, in case you want to setup the project first if directory does not exists
    commands:
      - go get github.com/eko/graphql
      - echo Your project is ready, don't forget to send an email to someone@acme.tld to obtain your access.
    env:
      - GIT_SSH_COMMAND: ssh -i /github/.ssh/id_rsa
  build: # Optional, in case you want to build the project before running it
    commands:
      - go build -mod vendor -o build/binary main.go
  run:
    commands: build/binary
    env: # Optional, in case you want to specify some environment variables for this app
      HTTP_PORT: 8005

You can define as many as you want.

First, the setup section helps to define commands that have to be run when application path is not found locally. This allows you to share your configuration with colleagues and setup a development environment in a same way for multiple developers.

Then, the hostname will be the hostname you want to use locally to access this application: in case your application opens a HTTP server, it will have to listen on this hostname.

command under the run section define how your application is launched and you can define environment variables for this process only using the env section.

Optionally, you can also add a build section that will be run just before the run one. When a change is detected on your application, both build & run sections will be re-played.

Configure forwards

There are actually 5 forward types available:

  • kubernetes: will target pods on Kubernetes and make a port-forward in order to let you access the service from your local instance,
  • kubernetes-remote will target pods on Kubernetes and deploy a proxy for this service that will forward all traffic occurring on your service locally: so you can run a local application and see queries from your environment hitting your local application,
  • ssh: will forward ports using SSH connection locally so you will be able to access a remote service from your local,
  • ssh-remote brings the ability to forward a remote traffic occurring over SSH on some ports into your machine.
  • proxy is a simple TCP proxy to access a service remotely from a custom hostname (or IP address) over a defined local hostname and port locally

Here are some configuration examples:

Type: kubernetes

<: &graphql-forward
  name: graphql
  type: kubernetes
  values:
    context: *kubernetes-context
    namespace: backend
    labels:
      app: graphql
    hostname: graphql.svc.local # Optional
    ports:
     - 8080:8000

labels you provide will be used to target your pods on Kubernetes hostname is the hostname that will be made available for you on your local machine

So here, your service will be available over http://graphql.svc.local:8080 and will be forwarded to port 8000 on your Kubernetes pods

Type: kubernetes-remote

Now, imagine that your GraphQL as takes its datasource using a gRPC API and you want to debug something on the environment: you need to run gRPC API locally and have all the traffic incoming to the pod on Kubernetes to be redirected on your machine. This is the role of kubernetes-remote forward type:

<: &grpc-api-kubernetes-remote
  name: grpc-api
  type: kubernetes-remote
  values:
    context: *kubernetes-context
    namespace: backend
    labels:
      app: grpc-api
    ports:
     - 8080:8080
     - 8001:8001

As the kubernetes port-forward, a port will be targeted using the values you provided and a proxy Docker image will be deployed on your environment that allows to remote-forward the trafic on your machine.

Type: ssh

A simple SSH port-forward can be made (ssh -L for hipsters):

<: &composieux-fr-local
  name: composieux-fr-local
  type: ssh
  values:
    remote: vincent@composieux.fr # SSH <user>@<hostname>
    args:
      - "-i/Users/name/.ssh/private_key"
    hostname: composieux.fr.svc.local # Optional
    ports:
     - 8080:80

For this forward type, we just need to know the remote that we will have to connect to over SSH and you can also add some SSH arguments such as here a specific private key, for instance.

With this example, I will be able to access my personal website on http://composieux.fr.svc.local:8080 locally, and it will forward traffic to http://composieux.fr:80.

Type: ssh-remote

As for the kubernetes-remote type but without the Kubernetes part: it will forward all traffic over a SSH instance and a specified port to a specified port locally:

<: &composieux-fr-remote
  name: composieux-fr-remote
  type: ssh-remote
  values:
    remote: vincent@composieux.fr # SSH <user>@<hostname>
    args:
      - "-i/Users/name/.ssh/private_key"
    ports:
     - 8080:80

With the configuration above, all traffic on port 80 on my personal website will be redirected on my personal machine on port 8080.

Type: proxy

Finally, the simple proxy forward type allows to simply use a local hostname and forward traffic to a specified hostname and port:

<: &elasticsearch-proxy
  name: elasticsearch-proxy
  type: proxy
  values:
    hostname: elasticsearch.svc.local
    proxy_hostname: vpc-xxx-rO6gjlqbkwzmzde.eu-west-3.es.amazonaws.com
    ports:
     - 9200:443

In this configuration, I use it to forward all queries made to my local hostname https://elasticsearch.svc.local to an AWS Amazon instance: https://vpc-xxx-rO6gjlqbkwzmzde.eu-west-3.es.amazonaws.com.

This is useful to fix a specified hostname in your development configuration and let Monday brings the right hostname at the moment you decide to run your Elasticsearch instance locally or proxified over an environment.

Configure projects

Well, you have your local applications and forwarded applications declared, it's now time to compose your projects. This is much simpler, here is an example:

 - name: graphql
   local:
    - *graphql-local
   forward:
    - *grpc-api-forward

Here, I create a graphql project that will run my GraphQL instance locally and forward the gRPC API over an environment.

You can define as many as local and forward applications you want.

Clone this wiki locally