From 567ddf47d91c1e7b881d5d84c776f414cfd86a0a Mon Sep 17 00:00:00 2001 From: Proskurin Kirill Date: Wed, 7 Sep 2016 13:50:37 +0300 Subject: [PATCH] Add Application definition doc Change-Id: I5dbb900acaf64cff34175fde9c5c9277973611ce --- doc/source/app_def_guide.rst | 234 +++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 2 files changed, 235 insertions(+) create mode 100644 doc/source/app_def_guide.rst diff --git a/doc/source/app_def_guide.rst b/doc/source/app_def_guide.rst new file mode 100644 index 00000000..bcabb3a8 --- /dev/null +++ b/doc/source/app_def_guide.rst @@ -0,0 +1,234 @@ +.. app_def_guide: + +========================================= +Application definition contribution guide +========================================= + +This guide covers CCP specific DSL, which is used by the CCP CLI to populate +k8s objects. + +Application definition files location +===================================== + +All application definition files should be located in the ``service/`` +directory, as a ``component_name.yaml`` file, for example: + +:: + + service/keystone.yaml + +All templates, such as configs, scripts, etc, which will be used for this +service, should be located in ``service//files``, for example: + +:: + + service/files/keystone.conf.j2 + +All files inside this directory are Jinja2 templates. Default variables for +these templates should be located in +``service/component_name/files/defaults.yaml`` inside the ``configs`` key. + +Understanding globals and defaults config +========================================= + +There are three config locations, which the CCP CLI uses: + +#. ``Global defaults`` - fuel_ccp/resources/defaults.yaml in ``fuel-ccp`` repo. +#. ``Component defaults`` - service/files/defaults.yaml in each component repo. +#. ``Global config`` - Optional. Set path to this config via + "--deploy-config /path" CCP CLI arg. + +Before deployment, CCP will merge all these files into one dict, using the +order above, so "component defaults" will override "global defaults" and +"global config" will override everything. + +Global defaults +--------------- + +This is project wide defaults, CCP keeps it inside fuel-ccp repository in +``fuel_ccp/resources/defaults.yaml`` file. This file defines global variables, +that is variables that are not specific to any component, like eth interface +names. + +Component defaults +------------------ + +Each component repository could contain a ``service/files/defaults.yaml`` file +with default config for this component only. + +Global config +------------- + +Optional config with global overrides for all services. Use it only if you need +to override some defaults. + +Config keys types +================= + +Each config could contain 3 keys: + +- ``configs`` + +- ``versions`` + +- ``sources`` + +- ``nodes`` + +Each key has its own purpose and isolation, so you have to add your variable +to the right key to make it work. + +configs key +----------- + +Isolation: + +- Used in service templates files (service/files/). + +- Used in application definition file service/component_name.yaml. + +Allowed content: + +- Any types of variables allowed. + +Example: + +:: + + configs: + keystone_debug: false + +So you could add "{{ keystone_debug }}" variable to you templates, which will +be rendered into "false" in this case. + +versions key +------------ + +Isolation: + +- Used in Dockerfile.j2 only. + +Allowed content: + +- Only versions of different software should be kept here. + +For example: + +:: + + versions: + influxdb_version: "0.13.0" + +So you could add this to influxdb Dockerfile.j2: + +:: + + curl https://dl.influxdata.com/influxdb/releases/influxdb_{{ influxdb_version }}_amd64.deb + +sources key +----------- + +Isolation: + +- Used in Dockerfile.j2 only. + +Allowed content: + +- This key has a restricted format, examples below. + +Remote git repository example: + +:: + + sources: + openstack/keystone: + git_url: https://github.com/openstack/keystone.git + git_ref: master + +Local git repository exaple: + +:: + + sources: + openstack/keystone: + source_dir: /tmp/keystone + +So you could add this to Dockerfile.j2: + +:: + + {{ copy_sources("openstack/keystone", "/keystone") }} + +CCP will use the chosen configuration, to copy git repository into Docker +container, so you could use it latter. + +network_topology key +-------------------- + +Isolation: + +- Used in service templates files (service/files/). + +Allowed content: + +- This key is auto-created by entrypoint script and populated with container + network topology, based on the following variables: ``private_interface`` and + ``public_interface``. + +You could use it to get the private and public eth IP address. For example: + +:: + + bind = network_topology["private"]["address"] + listen = network_topology["public"]["address"] + +nodes and roles key +------------------- + +Isolation: + +- Not used in any template file, only used by the CCP CLI to create a cluster + topology. + +Allowed content: + +- This key has a restricted format, example of this format can be found in + ``fuel-ccp`` git repository in ``etc/topology-example.yaml`` file. + +"CCP_*" env variables +--------------------- + +Isolation: + +- Used in service templates files (service/files/). + +Allowed content: + +- This variables are created from the application definition ``env`` key. + Only env keys which start with "CCP\_" will be passed to config hash. + +This is mainly used to pass some k8s related information to container, for +example, you could use it to pass k8s node hostname to container via this +variable: + +Create env key: + +:: + + env: + - name: CCP_NODE_NAME + valueFrom: + fieldRef: + fieldPath: spec.nodeName + +Use this variable in some config: + +:: + + {{ CCP_NODE_NAME }} + +Application definition language +=============================== + +Please refer to :doc:`dsl` for detailed description of CCP DSL syntax. + diff --git a/doc/source/index.rst b/doc/source/index.rst index 8692187a..90d06b3d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -23,6 +23,7 @@ Developer docs contributing docker + app_def_guide dsl Indices and tables