move documentation from managed tenants

.markdownlint.yaml

@@ -1,6 +1,6 @@
 default: true
 MD013:
-  line_length: 90
+  line_length: 120
   code_blocks: false
 # MD033/no-inline-html - Allow inline HTML
 MD033: false

content/en/docs/creating-addons/configure-vault-access.md

@@ -0,0 +1,204 @@
+---
+title: Configure Vault Access
+linkTitle: Vault Access
+---
+
+## Background
+
+Vault access is required by teams at paths like `mt-sre/tenants/<addon-name>/secrets/*` to store their secrets
+which are referenced by their `addon.yaml`s.
+For this, vault access needs to be set up for that team.
+
+Vault auth configuration is managed
+via [app-interface](https://gitlab.cee.redhat.com/gathomas/app-interface#manage-vault-configurations-via-app-interface).
+
+Multiple components have to be set up to provide vault access to the team. We will define the vault policy, oidc
+permission,
+role and then assign the role to the members of the team.
+
+### Vault Policy
+
+First we want to create a vault policy that allows access to the path that the team will store their secrets, i.e.
+`mt-sre/tenants/<addon-name>/secrets/*`. A vault policy is essentially a path with associated permissions (verbs).
+See the [HashiCorp Vault Policy documentation](https://developer.hashicorp.com/vault/docs/concepts/policies) for more
+information.
+
+To create the policy we follow
+Create a file under `data/services/vault.devshift.net/config/prod/policies` with the
+name `mt-sre-tenants-<team-name>-secrets-policy.yaml`
+with the following structure:
+
+```yaml
+---
+$schema: /vault-config/policy-1.yml
+
+labels:
+  service: vault.devshift.net
+
+name: "mt-sre-tenants-<team-name>-secrets-policy"
+instance:
+  $ref: /services/vault.devshift.net/config/instances/devshift-net.yml
+rules: |
+  path "mt-sre/metadata" {
+    capabilities = ["list"]
+  }
+  path "mt-sre/metadata/tenants" {
+    capabilities = ["list"]
+  }
+  path "mt-sre/metadata/tenants/<team-name>" {
+    capabilities = ["list"]
+  }
+  path "mt-sre/data/tenants/<team-name>/secrets/*" {
+    capabilities = ["list", "create", "read", "update", "delete"]
+  }
+  path "mt-sre/metadata/tenants/<team-name>/secrets/*" {
+    capabilities = ["list", "create", "read", "update", "delete"]
+  }
+
+```
+
+Take whatever subset of the rules above are needed.
+For example, under `data/services/vault.devshift.net/config/prod/policies/mt-sre-tenants-odf-secrets-policy.yml`, the
+content is:
+
+```yaml
+---
+$schema: /vault-config/policy-1.yml
+
+labels:
+  service: vault.devshift.net
+
+name: "mt-sre-tenants-odf-secrets-policy"
+instance:
+  $ref: /services/vault.devshift.net/config/instances/devshift-net.yml
+rules: |
+  path "mt-sre/metadata/tenants/odf/secrets/*" {
+    capabilities = ["create", "read", "update", "delete", "list"]
+  }
+  path "mt-sre/data/tenants/odf/secrets/*" {
+    capabilities = ["create", "read", "update", "delete", "list"]
+  }
+```
+
+See
+the [app-interface documentation about creating policies](https://gitlab.cee.redhat.com/service/app-interface#manage-vault-policies-vault-configpolicy-1yml)
+for more information.
+
+### OIDC Permission
+
+Next we will create an OIDC Permission to wrap the vault policy we just created.
+
+Create a file under `data/dependencies/vault/permissions/oidc/prod` with the
+name `mt-sre-tenants-<team-name>-oidc-permission.yaml`
+with the following structure:
+
+```yaml
+---
+$schema: /access/oidc-permission-1.yml
+
+labels:
+  service: vault.devshift.net
+
+name: mt-sre-tenants-<team-name>-oidc-permission
+description: mt-sre-tenants-<team-name>-oidc-permission vault devshift oidc permission
+
+instance:
+  $ref: /services/vault.devshift.net/config/prod/devshift-net.yml
+
+service: vault
+vault_policies:
+  - $ref: /services/vault.devshift.net/config/prod/policies/mt-sre-tenants-<team-name>-secrets-policy.yml
+```
+
+For example, under `data/dependencies/vault/permissions/oidc/prod/github-app-sre-vault-odf-team.yaml`
+(the difference in file name is for legacy reasons), the content is:
+
+```yaml
+---
+$schema: /access/oidc-permission-1.yml
+
+labels:
+  service: vault.devshift.net
+
+name: github-app-sre-vault-odf-team-oidc-vault
+description: github-app-sre-vault-odf-team vault devshift oidc permission
+
+instance:
+  $ref: /services/vault.devshift.net/config/prod/devshift-net.yml
+
+service: vault
+vault_policies:
+  - $ref: /services/vault.devshift.net/config/prod/policies/mt-sre-tenants-odf-secrets-policy.yml
+```
+
+### Role
+
+We now have to include this permission in a role that we can assign to the team members: *Note* this is an app-interface
+role, not to be confused with a vault role.
+
+Under `data/teams/<team-name>/roles` create a file called `app-sre-vault-<team-name>.yml` with the following contents:
+
+```yaml
+---
+$schema: /access/role-1.yml
+
+labels: { }
+name: app-sre-vault-odf
+
+permissions: [ ]
+
+oidc_permissions:
+  - $ref: /dependencies/vault/permissions/oidc/prod/mt-sre-tenants-<team-name>-oidc-permission.yaml
+```
+
+For example, the contents of  `data/teams/odf-managed-service/roles/app-sre-vault-odf.yml` is:
+
+```yaml
+---
+$schema: /access/role-1.yml
+
+labels: { }
+name: app-sre-vault-odf
+
+permissions: [ ]
+
+oidc_permissions:
+  - $ref: /dependencies/vault/permissions/oidc/prod/github-app-sre-vault-odf-team.yml
+```
+
+### Adding Users
+
+Now the users just need to be added with the role we just created.
+Under `data/teams/<team-name>/users` create files called `<redhat-username>.yml` with the following contents:
+
+```yaml
+---
+$schema: /access/user-1.yml
+
+labels: { }
+
+name: <Your name>
+org_username: <org username>
+github_username: <github username>
+quay_username: <quay username>
+
+roles: ## "roles" link your user to a certain role. Role in this case would point to the app-sre/your-team on Github.
+  - $ref: /teams/<team-dir-name>/roles/app-sre-vault-<team-name>.yml ## path to the roles file you created in the last step
+```
+
+For example, the contents of `data/teams/odf-managed-service/users/dbindra.yml` is:
+
+```yaml
+---
+$schema: /access/user-1.yml
+
+labels: { }
+
+name: Dhruv Bindra
+org_username: dbindra
+github_username: bindrad
+quay_username: dbindra
+
+roles:
+  - $ref: /teams/odf-managed-service/roles/app-sre-vault-odf.yml
+```

content/en/docs/creating-addons/managed-tenants-repository.md

@@ -11,3 +11,89 @@ be found in the
 . See the
 [create an addon](https://gitlab.cee.redhat.com/service/managed-tenants/-/blob/main/docs/tenants/create_an_addon.md)
 documentation page for a good starting point.
+
+## Structure
+
+The `addons` directory contains one subdirectory per Add-On that contains a `metadata` subdirectory.
+The `metadata` subdirectory contains one subdirectory per environment, which contains an Add-On metadata file
+for the corresponding environment. For example:
+
+```yaml
+addons/ocs-converged
+└── metadata
+    ├── production
+    │   └── addon.yaml
+    └── stage
+        └── addon.yaml
+```
+
+### addon imagesets
+
+Our tooling now supports creating imagesets for addons. Imageset of a new version of
+an addon sits inside a new directory called `addonimagesets/<environment>`. CPaaS/Tenants will need to create
+a merge request in <https://gitlab.cee.redhat.com/service/managed-tenants/> in order to notify
+MT-SRE of the availability of the new release. Each new addon version is a new file under the
+earlier mentioned `addonimagesets/<environment>` directory.
+
+See the [Imageset Specification](top-level-operator/imageset-specification.md) for more details about
+the imageset file.
+
+Example repository structure of an addon with imagesets:
+
+```bash
+mock-operator-with-imagesets
+├── addonimagesets
+│   └── stage
+│       ├── mock-operator.v1.0.0.yml
+│       ├── mock-operator.v1.0.2.yml
+└── metadata
+    └── stage
+        └── addon.yaml
+```
+
+The `addon.yaml` file would then reference the required imageset version
+using the attribute `addonImageSetVersion`. See the
+[Metadata Specification](top-level-operator/addon-metadata-file.md) for details.
+
+Ex:
+
+```yaml
+id: mock-operator
+name: Mock Operator
+description: This is a mock operator.
+icon: mock
+label: "api.openshift.com/addon-mock-operator"
+enabled: true
+addonOwner: Mock <mock@redhat.com>
+quayRepo: quay.io/osd-addons/mock-operator
+installMode: OwnNamespace
+targetNamespace: mock-operator
+namespaces:
+  - mock-operator
+namespaceLabels:
+  monitoring-key: mock
+namespaceAnnotations: {}
+ocmQuotaName: addon-mock-operator
+ocmQuotaCost: 1
+testHarness: quay.io/mock-operator/mock-operator-test-harness
+operatorName: mock-operator
+hasExternalResources: true
+defaultChannel: alpha
+bundleParameters:
+  useClusterStorage: "true"
+addonImageSetVersion: 1.0.0
+```
+
+#### metadata
+
+The `metadata` directory contains exclusively sub-directories, one per
+environment.
+
+The environment subdirectories host the corresponding `addons.yaml` metadata.
+See the [Metadata Specification](top-level-operator/addon-metadata-file.md) for details.
+
+#### bundles (deprecated)
+
+The `bundles` directory has been moved to the
+[managed-tenants-bundles repository](https://gitlab.cee.redhat.com/service/managed-tenants-bundles/-/blob/main/README.md)
+.

content/en/docs/creating-addons/merge-requests.md

@@ -0,0 +1,51 @@
+---
+title: Merge Requests
+---
+
+## Merge Request Review
+
+## Stage
+
+Merge Requests to stage can be self-serviced using the OWNERS file mechanism.
+
+## Production
+
+Any PR that promotes to prod will be manually reviewed to ensure that the addon
+has been present in the staging environment previously, in order to ensure that
+nothing goes directly to production without having had time in staging.
+
+## FAQ
+
+### Will my addon be automatically upgraded?
+
+For that, the new version bundle directory has to contain a
+`ClusterServiceVersion` manifest with the `replaces` field pointing to the version
+it will be upgraded from:
+
+```yaml
+...
+kind: ClusterServiceVersion
+...
+spec:
+  version: 1.19.0
+  replaces: example-operator.v1.18.0
+  ...
+```
+
+### Can I change metadata fields?
+
+By changing the metadata, the addon will be updated in the OCM API. That will
+affect new installations, but no cleanup is done to the already installed
+addons.
+
+### If my addon fails testing in prod, how will I be notified?
+
+Apart from the validations done here before publishing the addon, at the moment
+all the real world testing in done externally to this repository, either (or
+both) by using the OSD e2e framework or by assigning testing tasks to QA team.
+
+### Can I push to the addon catalog quay repo?
+
+No. The Quay.io organization is owned by the Add-Ons SRE team. All the pushes
+there  are automated and executed after the code is merged, which happens
+after all the tests are green.