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!