Environment definition file (env.yaml)

In order to describe an Environment, we use a single editable record, which contains its entire definition, including Applications / Services / Databases. We call it env.yaml
Overview
1
version:
2
  type: string
3
  required: true
4
  description: Bunnyshell parser version used for the current Environment definition.
5
kind:
6
  type: string
7
  required: true
8
  description: Type of entity being described, "Environment".
9
metadata: 
10
  type: hash
11
  required: false
12
  description: Key-value pairs; currently used to keep links with Bunnyshell entities.
13
name:
14
  type: string
15
  required: true
16
  description: Name of the Environment.
17
deploymentRules:
18
  type: hash
19
  required: false
20
  description: Settings serving Environment cloning and updating.
21
type:
22
  type: string
23
  required: true
24
  description: Specifies whether an Environment is permanent or ephemeral.
25
components:
26
  type: array
27
  required: true
28
  description: Contains the definitions of the Applications / Services / Databases composing the Environment.
Copied!
metadata
Currently, used to keep references to Bunnyshell internal entities, such as the ID of the Environment, or a unique hash to identify the Environment by, upon  - the Kubernetes namespace will contain it.
Also, arbitrary key-value pairs can be inserted here, for future use.
metadata Example
1
metadata:
2
  com.bunnyshell.k8s.id: 123
3
  com.bunnyshell.k8s.unique: alphanumeric
4
  com.bunnyshell.k8s.docker-compose-version: 3.4
5
  arbitrary: value
Copied!
Components
Applications, Services and Databases are defined under the components key.
components Composition Example:
1
components:
2
  - kind: Application
3
    version: v1
4
    name: php
5
    ...
6
  - kind: Application
7
    version: v1
8
    name: java
9
    ...
10
  - kind: Service
11
    version: v1
12
    name: nginx
13
    ...
14
  - kind: Database
15
    version: v1
16
    name: mysql
17
    ...
Copied!
Components Definition
1
components.N:
2
  kind:
3
    type: string
4
    required: true
5
    description: Type of the component - Application / Service / Database / StaticApplication / InitContainer / SidecarContainer
6
  version:
7
    type: string
8
    required: true
9
    description: Version used by the Bunnyshell parser for this component
10
  metadata:
11
    type: hash
12
    required: false
13
    description: Pretty name for the component, reference to the origin of the imported definition etc.
14
  name: php
15
    type: string
16
    required: true
17
    description: Component name, used to reference the component internally and name the Kubernetes services
18
  gitRepo:
19
    type: string
20
    required: false
21
    description: Git repository for the docker-compose.yml file which contained this component
22
  gitBranch: 
23
    type: string
24
    required: false
25
    description: Git branch for the docker-compose.yml file which contained this component
26
  gitApplicationPath: 
27
    type: string
28
    required: false
29
    description: Folder path within the Git repository; useful for monorepos
30
  gitDockerComposePath:
31
    type: string
32
    required: false
33
    description: Path of the docker-compose.yml file within the Git repository; may or may not contain the filename
34
  dockerCompose:
35
    type: hash
36
    required: true
37
    description: Contains information needed to build the images
38
  envVarMapping:
39
    type: hash
40
    required: true
41
    description: Supporting use of dynamic Env vars, such as Application / Service / Database URLs, generated by Bunnyshell; key-value pairs. Will be replaced with actual values before the deployment.
42
  k8s:
43
    resources: 
44
      type: hash
45
      required: true
46
      description: Specify resource allocation, in a Kubernetes-compatible way.
47
  pod:
48
      type: hash
49
      required: false
50
      description: Co-locate services on same pods and share folders between them (eg. programming language container + web server container, aka PHP-FPM + nginx).
51
  hosts: 
52
      type: array
53
      required: false
54
      description: Specify the host URL (domain + path + service port).
55
  preReleaseCommands: 
56
      type: array
57
      required: false
58
      description: Every new pod for this Application will first run these commands in order and wait until they are succesfull. Only after their success, the pod will start.
59
  cronJobs:
60
      type: array
61
      required: false
62
      description: A list of commands to be ran. Any command will be ran each time in a fresh container instance, so you cannot rely on running jobs on existing containers (eg. not suitable for log rotation).
63
  dbSeed:
64
      type: string
65
      required: false
66
      description: Used only for Databases. A string composed of a filename and a version. The files must be uploaded in Bunnyshell beforehand.
Copied!
components.N.dockerCompose Definition
1
dockerCompose:
2
  build:
3
    context: 
4
      type: string
5
      required: true
6
      description: Path where the docker build will be ran
7
    dockerfile:
8
      type: string
9
      required: true
10
      description: Filename of the dockerfile, within the specified path (context)
11
    args:
12
      type: hash
13
      required: false
14
      description: Build arguments, expressed as key-value pairs
Copied!
components.N.dockerCompose Example
1
dockerCompose:
2
  build:
3
    context: .docker/php
4
    dockerfile: Dockerfile
5
    args:
6
      buildno: 1
Copied!
components.N.k8s.resources Definition
1
  k8s:
2
    resources:
3
      requests:
4
        cpu: 
5
          type: string
6
          required: false
7
          description: Kubernetes-compatible values
8
        memory: 
9
          type: string
10
          required: false
11
          description: Kubernetes-compatible values
12
      limits:
13
        cpu: 
14
          type: string
15
          required: false
16
          description: Kubernetes-compatible values
17
        memory: 
18
          type: string
19
          required: false
20
          description: Kubernetes-compatible values
Copied!
components.N.k8s.resources Example
1
  k8s:
2
    resources:
3
      requests:
4
        cpu: 500m
5
        memory: "512Mi"
6
      limits:
7
        cpu: "1"
8
        memory: "1Gi"
Copied!
components.N.pod Definition
1
pod:
2
 init_containers:
3
        - type: array
4
        - required: false
5
        - description: The components of kind InitContainer that will run as an initContainer in this pod along with the main component
6
 sidecar_containers:
7
        - type: array
8
        - required: false
9
        - description: The components of kind SidecarContainer that will run as an containers in this pod along with the main component
Copied!
components.N.pod Example
1
pod:
2
  init_containers:
3
    -
4
      name: init-frontend
5
      environment:
6
          NODE_ENV: production
7
      shared_paths:
8
        -
9
          path: /opt/frontend/public
10
          target:
11
            path: /opt/nginx/public/static
12
            container: '@parent'
13
          initial_contents: '@self'
14
      shared_volumes:
15
         -
16
             name: node-modules-cache
17
             mount_path: /opt/frontend/node_modules
18
  sidecar_containers:
19
    -
20
      name: sidecar-backend
21
      environment:
22
        COMPOSER_HOME: /opt/.composer
23
      shared_paths:
24
        -
25
          path: /opt/backend/.etc/nginx/config
26
          target:
27
            path: /etc/nginx/config
28
            container: '@parent'
29
          initial_contents: '@self'
30
      shared_volumes:
31
         -
32
             name: backend-sessions
33
             mount_path: /opt/backend/sessions
Copied!
components.N.pod.*.N Definition
1
name:
2
  type: string
3
  required: true
4
  description: The name of a component of kind InitContainer for init_containers or kind SidecarContainer for sidecar_containers.
5
environment:
6
  type: hash
7
  required: false
8
  description: A key-value map of environment variables to inject into this init container or sidecar container.
9
shared_paths:
10
  type: array
11
  required: false
12
  description: ReadWrite paths that should be shared between current init or sidecar container and a target container in the pod.
13
shared_volumes:
14
  type: array
15
  required: false
16
  description: Volume mounts to be added to this init or sidecar container.
Copied!
components.N.pod.*.N.shared_paths.N Definition
1
path:
2
  type: string
3
  required: true
4
  description: A path from the current init/sidecar container
5
target:
6
  type: hash
7
  required: true
8
  description: A target for path sharing
9
  keys:
10
    container:
11
      type: string
12
      required: true
13
      description: A container in the same pod. Refer to the component where the pod is defined with '@parent'.
14
    path:
15
      type: string
16
      required: true
17
      description: A path in the defined target.container.
18
initial_contents:
19
  type: enum
20
  values: ['@self', '@target']
21
  required: true
22
  description: Shared path initial contents from either current init/sidecar container or target container.
Copied!
components.N.pod.*.N.shared_volumes.N Definition
1
name:
2
  type: string
3
  required: true
4
  description: A named volume as defined in docker compose specification.
5
mount_path:
6
  type: string
7
  required: true
8
  description: A path where the volume should be mounted in the current init/sidecar container.
Copied!
components.N.hosts Definition
1
hosts:
2
  - hostname: 
3
        type: string
4
        required: true
5
        description: Hostname prefix, will be suffixed with "-${env_unique}.bunnyenv.com"
6
    path: 
7
        type: string
8
        required: false
9
        description: URL path, if any
10
    servicePort:  
11
        type: string
12
        required: true
13
        description: "Public" port (not the container port), aka the one exposed through the Service definition
Copied!
components.N.hosts Example
1
hosts:
2
  - hostname: backend
3
    path: /
4
    servicePort: 8080
Copied!
components.N.cronJobs Definition
1
  cronJobs:
2
    - name: 
3
        type: string
4
        required: true
5
        description: The pretty name; a Kubernetes CronJob resource with the name "{service_name}.{cronjob_name}" will be created, to ensure uniqness in the namespace
6
      schedule: 
7
        type: string
8
        required: true
9
        description: Kubernetes Cron schedule syntax (https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#cron-schedule-syntax);
10
      command: 
11
        type: string
12
        required: true
13
        description: The command to be ran
Copied!
components.N.cronJobs Example
1
  cronJobs:
2
    - name: check-git-status
3
      schedule: "*/1 * * * *"
4
      command: php bin/console git:check-status 
Copied!
Complete Configuration Example
1
version: v1
2
kind: Environment
3
metadata:
4
  com.bunnyshell.k8s.id: 123
5
  com.bunnyshell.k8s.unique: {alphanumeric}
6
  com.bunnyshell.k8s.docker-compose-version: 3.4
7
  arbitrary: value
8
name: my-env
9
type: primary | ephemeral
10
components:
11
  - kind: SidecarContainer
12
    version: v1
13
    metadata:
14
      com.bunnyshell.k8s.display-name: PHP App
15
      com.bunnyshell.k8s.source-file: git.repo.com/.docker/docker-compose.yaml
16
      com.bunnyshell.k8s.source-file-hash: {alphanumeric}
17
      com.bunnyshell.k8s.source-block-hash: {alphanumeric}
18
      com.bunnyshell.k8s.source-name: php
19
    name: php
20
    gitRepo: [email protected]...
21
    gitBranch: master
22
    gitApplicationPath: / # optional; for monorepo apps
23
    gitDockerComposePath: / # the path of the docker-compose.yaml inside the git_repo
24
    dockerCompose:
25
      # image: ... # if present, `image` will be removed, we will build the image and after that we will add the image: with the value from our Amazon ECR
26
      build:
27
        context: .docker/php
28
        dockerfile: Dockerfile
29
        args:
30
          buildno: 1
31
    envVarMapping:
32
      API_PATH: BNS_INGRESS_URL_NGINX # BNS_ are auto-generated
33
    k8s:
34
      resources: # k8s resources for this service; k8s syntax
35
        requests:
36
          cpu: "0.5"
37
          memory: "100Mi"
38
        limits:
39
          cpu: "900m"
40
          memory: "0.5Gi"
41
    hosts: # you can add more
42
      - hostname: app # will be suffixed with -${env_unique}.bunnyenv.com
43
        path: / # optional
44
        servicePort: 8080
45
    preReleaseCommands: # every new pod for this Application will first run these commands in order and wait until they are succesfull; only after their success, the pod will start
46
      - php bin/console doctrine:migrations -y
47
    cronJobs:
48
      - name: check-git-status
49
        schedule: "*/1 * * * *" # k8s Cron schedule syntax (https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#cron-schedule-syntax);
50
        command: php bin/console git:check-status # this will be passed as an argument to `/bin/sh -c`
51
​
52
  - kind: InitContainer
53
    version: v1
54
    name: frontend
55
    gitRepo: [email protected]...
56
    gitBranch: master
57
    gitApplicationPath: / # optional; for monorepo apps
58
    dockerCompose:
59
      build:
60
        context: frontend
61
​
62
  - kind: Service
63
    version: v1
64
    metadata:
65
      com.bunnyshell.k8s.id: 123 # Bunnyshell ID, optional
66
      com.bunnyshell.k8s.display-name: Web Server
67
      com.bunnyshell.k8s.source-file: git.repo.com/.docker/docker-compose.yaml
68
      com.bunnyshell.k8s.source-file-hash: {alphanumeric}
69
      com.bunnyshell.k8s.source-block-hash: {alphanumeric}
70
      com.bunnyshell.k8s.source-name: nginx
71
    name: nginx
72
    gitRepo: [email protected]...
73
    gitBranch: master
74
    gitApplicationPath: / # optional; for monorepo apps
75
    gitDockerComposePath: / # the path of the docker-compose.yaml inside the git_repo
76
    dockerCompose:
77
      build:
78
        context: .docker/nginx
79
        dockerfile: Dockerfile
80
        args:
81
          buildno: 1
82
    envVarMapping:
83
    k8s:
84
      resources: # k8s resources for this service; k8s syntax
85
        requests:
86
          cpu: "0.5"
87
          memory: "100Mi"
88
        limits:
89
          cpu: "900m"
90
          memory: "0.5Gi"
91
    pod:
92
      init_containers:
93
        -
94
          name: frontend
95
          shared_paths:
96
            -
97
              path: /var/www/public # path on this service container (e.g. frontend)
98
              target:
99
                container: '@parent'
100
                path: /var/www/html/public # path on the pod-colocated service container (e.g. nginx)
101
              initial_contents: '@self'
102
      sidecar_containers:
103
        -
104
          name: php
105
    hosts: # you can add more
106
      - hostname: app # will be suffixed with -${env_unique}.bunnyenv.com
107
        path: / # optional
108
        servicePort: 8080
109
    preReleaseCommands:
110
    cronJobs:
111
​
112
  - kind: Database
113
    metadata:
114
      com.bunnyshell.k8s.id: 456 # Bunnyshell ID, optional
115
      com.bunnyshell.k8s.display-name: Database
116
      com.bunnyshell.k8s.source-file: git.repo.com/.docker/docker-compose.yaml
117
      com.bunnyshell.k8s.source-file-hash: {alphanumeric}
118
      com.bunnyshell.k8s.source-block-hash: {alphanumeric}
119
      com.bunnyshell.k8s.source-name: mysql
120
    name: mysql
121
    gitRepo: [email protected]...
122
    gitBranch: master
123
    gitApplicationPath: / # optional; for monorepo apps
124
    gitDockerComposePath: / # the path of the docker-compose.yaml inside the git_repo
125
    dockerCompose:
126
      build:
127
        context: .docker/mysql
128
        dockerfile: Dockerfile
129
        args:
130
          buildno: 1
131
    envVarMapping:
132
    k8s:
133
      resources: # k8s resources for this service; k8s syntax
134
        requests:
135
          cpu: "0.5"
136
          memory: "100Mi"
137
        limits:
138
          cpu: "900m"
139
          memory: "0.5Gi"
140
    podSharing:
141
    hosts:
142
    preReleaseCommands:
143
    cronJobs:
144
    dbSeed: anonymized-dumps/stage-complex-scenarios.sql:v3
Copied!
Docker Hub
Next - Reference Guide
Docker compose conversion support
Last modified 2d ago
Copy link
Contents
Overview
metadata
Components
components Composition Example:
Components Definition
Complete Configuration Example