From f37e7370578070f41e0de8128a5467983dd18ba0 Mon Sep 17 00:00:00 2001 From: Shubham Minglani Date: Wed, 31 May 2017 19:57:53 +0530 Subject: [PATCH 1/3] add opencompose extension proposal --- docs/proposals/extensions.md | 88 ++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/proposals/extensions.md diff --git a/docs/proposals/extensions.md b/docs/proposals/extensions.md new file mode 100644 index 00000000..b6df7f6d --- /dev/null +++ b/docs/proposals/extensions.md @@ -0,0 +1,88 @@ +## Proposal for extending an OpenCompose file with another OpenCompose file + +##### Scenario: + +Let's say, we have a sample OpenCompose file defining a Wordpress application - + +_wordpress-opencompose.yml_ - +```yaml +version: '0.1-dev' + +services: +- name: database + containers: + - image: mariadb:10 + env: + - name: MYSQL_ROOT_PASSWORD + value: rootpasswd + - name: MYSQL_DATABASE + value: wordpress + - name: MYSQL_USER + value: wordpress + - name: MYSQL_PASSWORD + value: wordpress + ports: + - port: 3306 + +- name: web + containers: + - image: wordpress:4 + env: + - name: WORDPRESS_DB_HOST + value: database:3306 + - name: WORDPRESS_DB_PASSWORD + value: wordpress + - name: WORDPRESS_DB_USER + value: wordpress + - name: WORDPRESS_DB_NAME + value: wordpress + ports: + - port: 80 + type: external +``` + +This file works fine for a developer, but since there is no persistent volumes defined here, we need to alter this for production use cases; but changing the original file disrupts the developer workflow. + +So, the production folks create another OpenCompose file which will extend _wordpress-opencompose.yml_ which will look like - + +_wordpress.extension.yml_ + +```yaml +version: '0.1-dev' +extends: wordpress-opencompose.yml + +services: +- name: database + env: + - name: MYSQL_ROOT_PASSWORD + secretRef: dbcreds/rootpassword + mounts: + - volumeRef: database + mountPath: /var/lib/mysql + +secrets: +- name: dbcreds + data: + - key: rootpassword + base64: dmVyeXN0cm9uZ3Bhc3N3b3Jk + +volumes: +- name: database + size: 100Mi + accessMode: ReadWriteOnce +``` + +With this file, +- the OpenCompose definitions which already exist in _wordpress-opencompose.yml_ are updated/overwritten, which in this case is the _database_ service, which gets a volume mount and a secret exposed. +- the OpenCompose definitions that do not exist in _wordpress-opencompose.yml_, are created, which in this case are the root level secrets and root level volumes. + +Now the command, `opencompose -f wordpress-opencompose.yml,wordpress.extension.yml convert` is run, the magic happens and wordpress runs happily in the wild. + +--- + +The extension file - +- does not have to be a legal OpenCompose file. It can be a complete OpenCompose file, in which case nothing will be overridden and only appended to the original file. +- include a root level `extends: ` that indicates which OpenCompose file(s) this file extends. +This means that one file can extend multiple OpenCompose file. +- _everything_ mentioned in the extension file takes precedence over the file it is extending, whenever a conflicting field appears. +- is passed normally like any other OpenCompose file besides the normal file with the `-f` directive, e.g. `opencompose -f original.yml,extension.yml convert` From c35a3cb23189f21e9d9e827ecb8d527d3b8c7197 Mon Sep 17 00:00:00 2001 From: Shubham Minglani Date: Mon, 5 Jun 2017 12:20:42 +0530 Subject: [PATCH 2/3] replace 'extends: file' to 'type: extension' --- docs/proposals/extensions.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/proposals/extensions.md b/docs/proposals/extensions.md index b6df7f6d..4bbba308 100644 --- a/docs/proposals/extensions.md +++ b/docs/proposals/extensions.md @@ -49,7 +49,7 @@ _wordpress.extension.yml_ ```yaml version: '0.1-dev' -extends: wordpress-opencompose.yml +type: extension services: - name: database @@ -82,7 +82,6 @@ Now the command, `opencompose -f wordpress-opencompose.yml,wordpress.extension.y The extension file - - does not have to be a legal OpenCompose file. It can be a complete OpenCompose file, in which case nothing will be overridden and only appended to the original file. -- include a root level `extends: ` that indicates which OpenCompose file(s) this file extends. -This means that one file can extend multiple OpenCompose file. +- specifies a root level `type: extension` field which makes it an extension file, which means this file is not expected to have legal OpenCompose syntax and mandatory fields can be missing. The validation will be carried out once the file is merged with the other files. - _everything_ mentioned in the extension file takes precedence over the file it is extending, whenever a conflicting field appears. - is passed normally like any other OpenCompose file besides the normal file with the `-f` directive, e.g. `opencompose -f original.yml,extension.yml convert` From d3a3ddda5b86a73f3e0004e1447e2e8146323510 Mon Sep 17 00:00:00 2001 From: Shubham Minglani Date: Thu, 8 Jun 2017 20:01:05 +0530 Subject: [PATCH 3/3] add operation info, and immutable keys table --- docs/proposals/extensions.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/proposals/extensions.md b/docs/proposals/extensions.md index 4bbba308..c2828cee 100644 --- a/docs/proposals/extensions.md +++ b/docs/proposals/extensions.md @@ -75,6 +75,30 @@ volumes: With this file, - the OpenCompose definitions which already exist in _wordpress-opencompose.yml_ are updated/overwritten, which in this case is the _database_ service, which gets a volume mount and a secret exposed. - the OpenCompose definitions that do not exist in _wordpress-opencompose.yml_, are created, which in this case are the root level secrets and root level volumes. +- the OpenCompose definitions can be deleted using the immutable keys for different fields - + +| field | immutable keys | +|--------------------------|-----------------------| +| services | name | +| containers | name | +| env | name | +| ports | servicePort | +| mounts | mountPath | +| emptyDirVolumes | name | +| volumes | name | + +Support, we want to delete the environment variable "foo", then out extension file with look like - + +```yaml +version: '0.1-dev' +type: extension + +services: +- name: database + env: + - name: foo + $operation: delete +``` Now the command, `opencompose -f wordpress-opencompose.yml,wordpress.extension.yml convert` is run, the magic happens and wordpress runs happily in the wild.