Merge remote-tracking branch 'origin/main' into rholling-SCS-docs

Author: maxwolfs

.gitignore

@@ -1,6 +1,13 @@
 # Content Dependencies from docs.package.json
 /repo_to_be_edited_
 /docs/02-iaas/components
+/docs/02-iaas/guides
+/docs/02-iaas/guides/configuration-guides
+/docs/02-iaas/guides/deploy-guide
+/docs/02-iaas/guides/operations-guide
+/docs/02-iaas/guides/troubleshooting-guides
+/docs/02-iaas/guides/upgrade-guides
+/docs/02-iaas/guides/index.md
 /docs/02-iaas/deployment-examples/cloud-in-a-box
 /docs/02-iaas/deployment-examples/testbed
 /docs/03-container/components

README.docs.md

@@ -3,8 +3,8 @@
 ## Licenses
 
 The content of this repository is published under multiple licenses.
-All files within `docs` are licensed under [CC-BY-SA 4.0](LICENSE-DOCS).
-All source code is licensed under the [MIT](LICENSE-CODE) license.
+All documentation content files within `docs, dev-docs, standards and community` are licensed under [CC-BY-SA 4.0](LICENSE-DOCS).
+All source code of this documentation page is licensed under the [MIT](LICENSE-CODE) license.
 
 ## Overview
 

README.md

@@ -13,13 +13,15 @@ to achieve that goal. To simplify connecting the different parts of SCS
 to customer owned IAM solutions, SCS deploys Keycloak as central Identity
 Provider (IdP) service.
 
+Currently this is deployed automatically only in the [osism/testbed](https://docs.scs.community/docs/iaas/guides/deploy-guide/examples/testbed/),
+which provides [its own documentation for authentication with OIDC](https://docs.scs.community/docs/iaas/guides/deploy-guide/examples/testbed#authentication-with-oidc).
+
 The following sections describe how this is done.
 
 ## 1. IaaS / OpenStack
 
 To provide Infrastrucure as a Service SCS builds upon
-OpenStack. See the `openstack-federation-via-oidc` document
-in [the iam section of this documentation](https://docs-staging.scs.community/docs/iam/)
+OpenStack. See section [OpenStack Federation via OpenID-Connect](https://docs.scs.community/dev-docs/operations/iam/openstack-federation-via-oidc)
 for more details on identity federation for OpenStack.
 
 ## 2. CaaS

dev-docs/operations/iam/identity-federation-in-scs.md

@@ -279,13 +279,15 @@ For this purpose Zuul creates its own public/private key pair for each project.
 public key to create secrets. But only Zuul will be able to decrypt these values. To avoid the user
 to be responsible for the correct encryption there is an zuul-client tool that will do this for you.
 
-Example:
+Example (reading from stdin and writing to stdout):
 
 ```bash
-zuul-client --zuul-url ZUUL_URL  encrypt --tenant TENANT --project ORGANIZATION/PROJECT --infile creds.yaml --outfile clouds.yaml.enc
+zuul-client --zuul-url ZUUL_URL encrypt --tenant SCS --project SovereignCloudStack/REPO
 ```
 
-The content may look like this:
+Add `--infile INFILE` or `--outfile OUTFILE` if you prefer to work with files directly.
+
+The output might look like this:
 
 ```yaml
 - secret:
@@ -307,6 +309,22 @@ The content may look like this:
 You may use this content or the file to provide it as a secret. You just have to update the `<name>` and the
 `<fieldname>` part.
 
+The secret name has to be unique across all projects. Because of this, we have a naming convention in the
+`SovereignCloudStack` organisation that ensures that a secret has a unique name.
+
+Our convention is as follows. There is only one secret per Zuul configuration per project (for exceptions,
+see below). This secret always has a name in the form
+`SECRET_REPOSITORY_NAME`. For instance, if a secret in the `SovereignCloudStack/k8s-cluster-api-provider`
+repository is
+to be used, it is given the name `SECRET_K8S_CLUSTER_API_PROVIDER`. The name of the repository is
+always written in capital letters. A dash is replaced with an underscore. Any number of values
+(`<fieldname>: !encrypted/pkcs1-oaep`) can then be assigned to this one secret.
+
+In certain cases, it can be undesireable to expose all secret information to all jobs in a project.
+Then additional secrets may be used, whose names have to be formed by appending an underscore and some
+upper-case prefix to the name of the primary secret. For instance, we might use the
+name `SECRET_REPOSITORY_NAME_FOOBAR`.
+
 Official documentation:
 
 1. [Secrets documentation](https://zuul-ci.org/docs/zuul/latest/config/secret.html#secret)
@@ -320,30 +338,47 @@ For a basic but working example the following content may be written into a `zuu
 # zuul.yaml content
 ---
 - secret:
-    name: mySecret
+    name: SECRET_REPOSITORY_NAME
     data:
-      secretValue: !encrypted/pkcs1-oaep
-        - <ENCYPTED_DATA>
+      secretValue1: !encrypted/pkcs1-oaep
+        - <ENCRYPTED_DATA>
+      secretValue2: !encrypted/pkcs1-oaep
+        - <ENCRYPTED_DATA>
+      secretValue3: !encrypted/pkcs1-oaep
+        - <ENCRYPTED_DATA>
 
 - job:
     name: myFirstTestJob
     parent: base
     secrets:
-      - name: secretName # The name of the secret that is used within "playbooks/testPlaybook.yaml"
-        secret: mySecret
+      - name: secretName  # The name of the secret that is used within "playbooks/testPlaybook.yaml"
+        secret: SECRET_REPOSITORY_NAME
     run: playbooks/testPlaybook.yaml
 
+- job:
+    name: mySecondTestJob
+    parent: base
+    run: playbooks/testPlaybookTwo.yaml
+
 - project:
-    check:
+    tag:
       jobs:
         - myFirstTestJob
+    check:
+      jobs:
+        - mySecondTestJob
 ```
 
-This will run you job `myFirstTestJob` when ever the `check` pipeline is triggered.
-Within SCS this pipeline is always triggered if you open, change or reopen a pull request.
-The `check` pipeline can also be triggered manually if you write a comment on an already
+This will run the job `myFirstTestJob` whenever the `tag` pipeline is triggered, and
+`mySecondTestJob` whenever `check` is triggered.
+
+Within SCS the `check` pipeline is always triggered if you open, change or reopen a pull request.
+This pipeline can also be triggered manually if you write a comment on an already
 existing pull request and place the string `recheck` in it.
 
+Recall that the first test job cannot run on the same pipeline because it uses a secret.
+The `tag` pipeline is run whenever a new tag is created.
+
 The path to you playbook is always the full path within the repository. The playbook
 contains the tasks you actually want to run on all or a specific subset of nodes.
 Example playbook:
@@ -354,5 +389,5 @@ Example playbook:
 - hosts: all
   tasks:
     - debug:
-        msg: 'Debug print my secrets! {{ secretName.secretValue }}' # do not do this as it will expose your secrets
+        msg: 'Debug print my secrets! {{ secretName.secretValue1 }}'  # do not do this as it will expose your secrets
 ```

dev-docs/operations/operations/zuul-ci-cd-quickstart-user-guide.md

@@ -7,13 +7,7 @@
   },
   {
     "repo": "osism/osism.github.io",
-    "source": "docs/guides/operations-guide/openstack/image-manager.md",
-    "target": "docs/02-iaas/components",
-    "label": ""
-  },
-  {
-    "repo": "osism/osism.github.io",
-    "source": "docs/guides/operations-guide/openstack/flavor-manager.md",
+    "source": "docs/guides/operations-guide/openstack/day2-operations/*",
     "target": "docs/02-iaas/components",
     "label": ""
   },
@@ -37,8 +31,8 @@
   },
   {
     "repo": "osism/osism.github.io",
-    "source": "docs/advanced-guides",
-    "target": "docs/02-iaas/deployment-examples",
-    "label": "cloud-in-a-box"
+    "source": "docs/guides",
+    "target": "docs/02-iaas/",
+    "label": ""
   }
 ]

docs.package.json

@@ -18,7 +18,7 @@ A standardized environment promotes interoperability, reduces vendor lock-in, an
 
 ## Where can I find the SCS standards?
 
-The SCS standards are available on the standards pages within our documentation page. [Find them here](https://docs.scs.community/standards/)
+The SCS standards are available on the standards pages within our documentation page. [Find them here](https://docs.scs.community/standards)
 
 ## How is the SCS different from other cloud environments (e.g. AWS, Azure,...)?
 
@@ -46,7 +46,7 @@ IaaS stands for Infrastructure as a Service, providing virtualized computing res
 
 ## How is the IaaS layer structured?
 
-IaaS typically comprises virtual machines, storage, and network resources, all offered as scalable services. [Find the architecture here](#)
+IaaS typically comprises virtual machines, storage, and network resources, all offered as scalable services. [Find the architecture here](https://doc.scs.community/docs/category/iaas-layer)
 
 ## What does CaaS mean? (Container Layer)
 
@@ -56,27 +56,27 @@ CaaS refers to Container as a Service, where providers offer container orchestra
 
 **As a user**:
 
-- Existing SCS Clouds: Explore and test on any of the cloud providers offering SCS. [Choose one from here](#)
+- Existing SCS Clouds: Explore and test on any of the cloud providers offering SCS. [Choose one from here](https://doc.scs.community/standards/certification/overview#compliant-cloud-environments)
 
 **As a Cloud Service Provider**:
 
-- **Cloud in a Box**: Start with our pre-packaged solutions. [Link to Ciab](#)
-- **Testbed**: Use the SCS test environment to experiment. [Link to Testbed/deployment example](#)
+- **Cloud in a Box**: Start with our pre-packaged solutions. [Link to Ciab](https://doc.scs.community/docs/iaas/deployment-examples/cloud-in-a-box/advanced-guides/cloud-in-a-box)
+- **Testbed**: Use the SCS test environment to experiment. [Link to Testbed/deployment example](https://doc.scs.community/docs/iaas/deployment-examples/cloud-in-a-box/advanced-guides/testbed)
 
 ## I want to use an SCS Cloud! How do I get started?
 
 **As a user**:
 
-- Browse our [list of providers](#) and choose one that fits your needs.
+- Browse our [list of providers](https://doc.scs.community/standards/certification/overview#compliant-cloud-environments) and choose one that fits your needs.
 
 **As a Cloud Service Provider**:
 
-- Adopt SCS standards and utilize our [resources and tools](#) to integrate them.
+- Adopt SCS standards and utilize our [resources and tools](https://doc.scs.community/docs/category/components) to integrate them.
 
 ## I want to use the SCS in my company and build my own cloud! Where do I start?
 
-Start by understanding SCS standards and then move on to the reference implementation. [Link to guide](#).
+Start by understanding SCS standards and then move on to the reference implementation. [Link to guide](https://doc.scs.community/standards/)).
 
 ## I have a technical problem. Where can I find help?
 
-Refer to our support section or check our community channels for assistance. [Link to community](#).
+Refer to our support section or check our community channels for assistance. [Link to community](https://doc.scs.community/community).