356 lines
11 KiB
ReStructuredText
356 lines
11 KiB
ReStructuredText
..
|
|
Copyright 2018 AT&T Intellectual Property.
|
|
All Rights Reserved.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
Document Fundamentals
|
|
=====================
|
|
|
|
The definition of a site consists of a set of small YAML documents that
|
|
are managed by Deckhand_. Each document is identified by a ``schema`` top-level
|
|
key and the ``metadata.name`` value that uniquely identifies a particular
|
|
document of the type ``schema``. Deckhand provides functionality allowing
|
|
documents to be authored such that data from multiple documents can be merged.
|
|
|
|
* Abstact vs Concrete - Documents define a value in ``metadata.layeringDefinition.abstract`` to
|
|
determine if a document is abstract (a value of ``true``) or concrete (a value of ``false``).
|
|
When calling the ``/revisions/{id}/rendered-documents`` API, only concrete documents are returned.
|
|
* Layering - Document layering_ is used
|
|
for whole documents that have known defaults but may need to be transformed in specific instances.
|
|
* Substitution - Data substitution_ is
|
|
used for extracting particular values from a document's data section (whole or in-part) and
|
|
inserting that data into a destination document (at the root of the data section or deeper
|
|
into a document).
|
|
|
|
Shared Documents
|
|
================
|
|
|
|
Secrets
|
|
-------
|
|
|
|
Several generic document types_ exist to support encryption of sensitive data.
|
|
|
|
These must be utilized for all data considered sensitive.
|
|
|
|
Global Catalogue Documents
|
|
--------------------------
|
|
|
|
`Deckhand`_'s layering functionality can be utilized in several ways, i.e site
|
|
definitions. At the ``global`` layer there will be several documents providing
|
|
different configurations for an object or service. Each of these will be
|
|
abstract documents. They can be incorporated into a particular site definition
|
|
by creating a concrete child document in the ``site`` layer that selects the
|
|
correct ``global`` parent. The child can then do further customization on the
|
|
configuration if needed.
|
|
|
|
As a best practice, ``global`` level documents using the catalog pattern
|
|
should utilize the layering labels ``component`` and ``configuration`` to
|
|
provide a consistent method for children documents select the correct parent.
|
|
The below example shows a set of documents for two configuration options for
|
|
OpenStack Keystone: one using local SQL-backed identity stores and one using
|
|
an LDAP backend. A site definition can then select and customize the appropriate
|
|
option.
|
|
|
|
When using a catalogue document, it is important to review that document
|
|
to ensure you understand all the requirements for it.
|
|
|
|
* Abstract documents are not required to be fully formed, so selecting
|
|
a catalogue document may require the child document to add data so
|
|
the document passes validation. In the below example, the child document
|
|
adds several required fields to the catalogue Chart: ``chart_name``,
|
|
``release``, and ``namespace``.
|
|
* A catalogue document may define substitutions with the expectation
|
|
that the substitution source documents are defined at a lower layer.
|
|
In the example below, all of the required credentials in the chart
|
|
are defined as substitutions in the ``global`` catalogue document,
|
|
but the source documents for the substitutions are defined in the
|
|
``site`` layer.
|
|
|
|
This catalogue pattern can also be utilized for the ``type`` layer
|
|
if needed.
|
|
|
|
.. _Deckhand: https://airship-deckhand.readthedocs.io
|
|
.. _layering: https://airship-deckhand.readthedocs.io/en/latest/overview.html#layering
|
|
.. _substitution: https://airship-deckhand.readthedocs.io/en/latest/overview.html#substitution
|
|
.. _types: https://airship-deckhand.readthedocs.io/en/latest/users/document-types.html#provided-utility-document-kinds
|
|
|
|
|
|
Global Layer
|
|
------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: ldap-backed-keystone
|
|
labels:
|
|
component: keystone
|
|
configuration: ldap-backed
|
|
layeringDefinition:
|
|
abstract: true
|
|
layer: global
|
|
storagePolicy: cleartext
|
|
substitutions:
|
|
- src:
|
|
schema: deckhand/Passphrase/v1
|
|
name: keystone_admin_password
|
|
path: .
|
|
dest:
|
|
path: .values.endpoints.identity.auth.admin.password
|
|
- src:
|
|
schema: deckhand/Passphrase/v1
|
|
name: mariadb_admin_password
|
|
path: .
|
|
dest:
|
|
path: .values.endpoints.oslo_db.auth.admin.password
|
|
- src:
|
|
schema: deckhand/Passphrase/v1
|
|
name: mariadb_keystone_password
|
|
path: .
|
|
dest:
|
|
path: .values.endpoints.oslo_db.auth.user.password
|
|
- src:
|
|
schema: pegleg/SoftwareVersions/v1
|
|
name: software-versions
|
|
path: .charts.ucp.keystone
|
|
dest:
|
|
path: .source
|
|
- src:
|
|
schema: pegleg/StringValue/v1
|
|
name: ldap_userid
|
|
src: .
|
|
dest:
|
|
path: .values.conf.ks_domains.cicd.identity.ldap.user
|
|
pattern: '(^USERID)'
|
|
- src:
|
|
schema: deckhand/Passphrase/v1
|
|
name: ldap_userid_password
|
|
path: .
|
|
dest:
|
|
path: .values.conf.ks_domain.cicd.identity.ldap.password
|
|
data:
|
|
install:
|
|
no_hooks: false
|
|
upgrade:
|
|
no_hooks: false
|
|
pre:
|
|
delete:
|
|
- type: job
|
|
labels:
|
|
job-name: keystone-db-sync
|
|
- type: job
|
|
labels:
|
|
job-name: keystone-db-init
|
|
post:
|
|
delete: []
|
|
create: []
|
|
values:
|
|
conf:
|
|
keystone:
|
|
identity:
|
|
driver: sql
|
|
default_domain_id: default
|
|
domain_specific_drivers_enabled: True
|
|
domain_configurations_from_database: True
|
|
domain_config_dir: /etc/keystonedomains
|
|
ks_domains:
|
|
cicd:
|
|
identity:
|
|
driver: ldap
|
|
ldap:
|
|
url: "ldap://your-ldap-server.example.com"
|
|
user: "USERID@example.com"
|
|
password: USERID_PASSWORD_REPLACEME
|
|
suffix: "dc=example,dc=com"
|
|
query_scope: sub
|
|
page_size: 1000
|
|
user_tree_dn: "DC=example,DC=com"
|
|
user_objectclass: user
|
|
user_name_attribute: sAMAccountName
|
|
user_mail_attribute: mail
|
|
user_enabled_attribute: userAccountControl
|
|
user_enabled_mask: 2
|
|
user_enabled_default: 512
|
|
user_attribute_ignore: "default_project_id,tenants,projects,password"
|
|
replicas: 2
|
|
labels:
|
|
node_selector_key: ucp-control-plane
|
|
node_selector_value: enabled
|
|
...
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: sql-backed-keystone
|
|
labels:
|
|
component: keystone
|
|
configuration: sql-backed
|
|
layeringDefinition:
|
|
abstract: true
|
|
layer: global
|
|
substitutions:
|
|
- src:
|
|
schema: deckhand/Passphrase/v1
|
|
name: keystone_admin_password
|
|
path: .
|
|
dest:
|
|
path: .values.endpoints.identity.auth.admin.password
|
|
- src:
|
|
schema: deckhand/Passphrase/v1
|
|
name: mariadb_admin_password
|
|
path: .
|
|
dest:
|
|
path: .values.endpoints.oslo_db.auth.admin.password
|
|
- src:
|
|
schema: deckhand/Passphrase/v1
|
|
name: mariadb_keystone_password
|
|
path: .
|
|
dest:
|
|
path: .values.endpoints.oslo_db.auth.user.password
|
|
- src:
|
|
schema: pegleg/SoftwareVersions/v1
|
|
name: software-versions
|
|
path: .charts.ucp.keystone
|
|
dest:
|
|
path: .source
|
|
data:
|
|
timeout: 300
|
|
install:
|
|
no_hooks: false
|
|
upgrade:
|
|
no_hooks: false
|
|
pre:
|
|
delete:
|
|
- name: keystone-bootstrap
|
|
type: job
|
|
labels:
|
|
application: keystone
|
|
component: bootstrap
|
|
- name: keystone-credential-setup
|
|
type: job
|
|
labels:
|
|
application: keystone
|
|
component: credential-setup
|
|
- name: keystone-db-init
|
|
type: job
|
|
labels:
|
|
application: keystone
|
|
component: db-init
|
|
- name: keystone-db-sync
|
|
type: job
|
|
labels:
|
|
application: keystone
|
|
component: db-sync
|
|
- name: keystone-fernet-setup
|
|
type: job
|
|
labels:
|
|
application: keystone
|
|
component: fernet-setup
|
|
values: {}
|
|
source: {}
|
|
...
|
|
|
|
Site Layer
|
|
----------
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: ucp-helm-toolkit
|
|
layeringDefinition:
|
|
abstract: false
|
|
layer: site
|
|
substitutions:
|
|
- src:
|
|
schema: pegleg/SoftwareVersions/v1
|
|
name: software-versions
|
|
path: .charts.ucp.helm-toolkit
|
|
dest:
|
|
path: .source
|
|
data:
|
|
chart_name: ucp-helm-toolkit
|
|
release: ucp-helm-toolkit
|
|
namespace: ucp
|
|
timeout: 100
|
|
values: {}
|
|
source: {}
|
|
dependencies: []
|
|
...
|
|
---
|
|
schema: armada/Chart/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: ucp-keystone
|
|
layeringDefinition:
|
|
abstract: false
|
|
layer: site
|
|
parentSelector:
|
|
component: keystone
|
|
configuration: ldap-backed
|
|
actions:
|
|
- method: merge
|
|
path: .
|
|
data:
|
|
chart_name: ucp-keystone
|
|
release: ucp-keystone
|
|
namespace: ucp
|
|
dependencies:
|
|
- ucp-helm-toolkit
|
|
...
|
|
---
|
|
schema: deckhand/Passphrase/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: ldap_userid_password
|
|
storagePolicy: encrypted
|
|
data: a-secret-password
|
|
...
|
|
---
|
|
schema: deckhand/Passphrase/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: keystone_admin_password
|
|
storagePolicy: encrypted
|
|
data: a-secret-password
|
|
...
|
|
---
|
|
schema: deckhand/Passphrase/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: mariadb_admin_password
|
|
storagePolicy: encrypted
|
|
data: a-secret-password
|
|
...
|
|
---
|
|
schema: deckhand/Passphrase/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: mariadb_keystone_password
|
|
storagePolicy: encrypted
|
|
data: a-secret-password
|
|
...
|
|
---
|
|
schema: pegleg/StringValue/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: keystone_ldap_userid
|
|
storagePolicy: cleartext
|
|
data: myuser
|
|
...
|