Merge pull request #3 from stakater/migrate-docs

Migrate docs

.dockerignore

@@ -0,0 +1 @@
+.git*

.github/md_config.json

@@ -0,0 +1,17 @@
+{
+  "aliveStatusCodes": [429, 200, 520], 
+  "ignorePatterns": [
+    {
+      "pattern": "^(https://stakater).+"
+    },
+    {
+      "pattern": "^(http://nexus).+"
+    },
+    {
+      "pattern": "^(https://nexus).+"
+    },
+    {
+      "pattern": "^(https://docs.github.com).+"
+    }
+  ]
+}

.github/workflows/pull_request.yaml

@@ -0,0 +1,23 @@
+name: Pull Request
+
+on:
+  pull_request:
+    branches:
+      - 'main'
+
+jobs:
+  qa:
+    uses: stakater/.github/.github/workflows/[email protected]
+    with:
+      MD_CONFIG: .github/md_config.json
+      DOC_SRC: content
+      MD_LINT_CONFIG: .markdownlint.yaml
+  build:
+    uses: stakater/.github/.github/workflows/[email protected]
+    with:
+      DOCKER_FILE_PATH: Dockerfile
+    secrets:
+      CONTAINER_REGISTRY_URL: ${{ secrets.STAKATER_NEXUS_PREPROD_REGISTRY }}
+      CONTAINER_REGISTRY_USERNAME: ${{ secrets.STAKATER_NEXUS_PREPROD_USERNAME }}
+      CONTAINER_REGISTRY_PASSWORD: ${{ secrets.STAKATER_NEXUS_PREPROD_PASSWORD }}
+      SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }}

.github/workflows/push.yaml

@@ -0,0 +1,19 @@
+name: Push
+
+on:
+  push:
+    branches:
+      - 'main'
+
+jobs:
+  push:
+    uses: stakater/.github/.github/workflows/[email protected]
+    with:
+      DOCKER_FILE_PATH: Dockerfile
+      RELEASE_BRANCH: main
+    secrets:
+      CONTAINER_REGISTRY_URL: ${{ secrets.STAKATER_NEXUS_PREPROD_REGISTRY }}/stakater
+      CONTAINER_REGISTRY_USERNAME: ${{ secrets.STAKATER_NEXUS_PREPROD_USERNAME }}
+      CONTAINER_REGISTRY_PASSWORD: ${{ secrets.STAKATER_NEXUS_PREPROD_PASSWORD }}
+      SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }}
+      GH_TOKEN: ${{ secrets.STAKATER_GITHUB_TOKEN }}

.github/workflows/release.yaml

@@ -0,0 +1,12 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    uses: stakater/.github/.github/workflows/[email protected]
+    secrets:
+      SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }}

.gitignore

@@ -0,0 +1,22 @@
+# Dist files
+dist/
+lib/
+
+# Test temp files
+**/__fixtures__/.temp/
+
+# Test coverage files
+coverage/
+
+# MacOS Desktop Services Store
+.DS_Store
+
+# Log files
+*.log
+
+# Typescript build info
+*.tsbuildinfo
+node_modules
+
+# Build files
+site/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vocabulary"]
+	path = vocabulary
+	url = [email protected]:stakater/vocabulary.git

.markdownlint.yaml

@@ -0,0 +1,6 @@
+{
+  "MD007": { "indent": 4 },
+  "MD013": false,
+  "MD024": false,
+  "MD046": false,
+}

.vale.ini

@@ -0,0 +1,9 @@
+StylesPath = "vocabulary/styles"
+MinAlertLevel = warning
+
+Vocab = "Stakater"
+
+# Only check MarkDown files
+[*.md]
+
+BasedOnStyles = Vale

Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.11-alpine as builder
+
+RUN pip3 install mkdocs-material mkdocs-mermaid2-plugin
+
+# set workdir
+RUN mkdir -p $HOME/application
+WORKDIR $HOME/application
+
+# copy the entire application
+COPY --chown=1001:root . .
+
+# build the docs
+RUN mkdocs build
+
+FROM nginxinc/nginx-unprivileged:1.23-alpine as deploy
+COPY --from=builder $HOME/application/site/ /usr/share/nginx/html/
+COPY default.conf /etc/nginx/conf.d/
+
+# set non-root user
+USER 1001
+
+LABEL name="Stakater Secrets Management Documentation" \
+      maintainer="Stakater <[email protected]>" \
+      vendor="Stakater" \
+      release="1" \
+      summary="Documentation for Stakater Secrets Management"
+
+EXPOSE 8080:8080/tcp
+
+CMD ["nginx", "-g", "daemon off;"]

README.md

@@ -1 +1 @@
-# secrets-docs
+# Stakater Secrets Management

content/external-secret-operator/getting-started.md

@@ -0,0 +1,47 @@
+# Getting Started with External Secret Operator
+
+To use External Secret Operator for your application, you need to perform the following steps:
+
+- [Login to Vault](../vault.md#authentication)
+- [Add secrets in Vault](../vault.md#create-secrets)
+- Configure `ExternalSecrets` in Helm values
+
+## Prerequisite
+
+Tenant `CustomResource` should be using template named as `tenant-vault-access`:
+
+```yaml
+apiVersion: tenantoperator.stakater.com/v1alpha1
+kind: Tenant
+metadata:
+  name: gabbar
+spec:
+  users:
+    owner:
+    - user1
+    - user2
+  quota: medium
+  namespacetemplate:
+    templateInstances:
+    - spec:
+        template: tenant-vault-access
+        sync: true
+```
+
+## Configure ExternalSecrets in Helm values
+
+In your `deploy/values.yaml`, enable `externalSecret` and provide details of the secret path in Vault:
+
+```yaml
+externalSecret:
+    enabled: true
+    secretStore:
+      name: tenant-vault-secret-store
+    files:   
+     inventory-postgres: #Name of Kubernetes Secret
+      data:
+        postgresql-password: #Name of Kubernetes Secret Key
+          remoteRef:
+            key: inventory-postgres #Name of Vault Secret
+            property: postgresql-password #Name of Vault Secret Key
+```

content/external-secret-operator/introduction.md

@@ -0,0 +1,58 @@
+# External Secret Operator
+
+A Kubernetes secret contains sensitive information decoupled from the application code and stored in key-value pairs. The Secret object provides a declarative API that makes it easy for application pods to access secret data. Kubernetes secrets however do not support storing or retrieving secret data from external secret management systems, such as HashiCorp Vault.
+
+_External Secrets_ solves this problem by providing access to secrets stored externally. It does this by adding an `ExternalSecret` object to Kubernetes using a [CustomResourceDefinition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). Developers specify the secret management system as `backendType` and the access properties in the manifest.
+
+SAAP uses the _External Secrets Operator_ to integrate HashiCorp Vault. The operator synchronizes secrets from external APIs into Kubernetes with the help of custom API resources: `ExternalSecret`, `SecretStore` and `ClusterSecretStore`.
+
+## Secret Store
+
+A secret store defines how to fetch the data. It defines the provider, such as Vault, its server address, the path for secrets, and its authentication method, e.g. service account bound with Vault role and policy:
+
+```yaml
+apiVersion: external-secrets.io/v1alpha1
+kind: SecretStore
+metadata:
+    name: tenant-vault-secret-store
+spec:
+    provider:
+    vault:
+        server: "http://vault.stakater-vault:8200"
+        path: "gabbar/kv"
+        version: "v2"
+        auth:
+        kubernetes:
+          mountPath: "kubernetes"
+          role: "gabbar-dev"
+          serviceAccountRef:
+            name: "tenant-vault-access"
+            namespace: "gabbar-dev"
+```
+
+## External Secret
+
+An external secret declares what data to fetch. It has a reference to a SecretStore which knows how to access that data:
+
+```yaml
+apiVersion: external-secrets.io/v1alpha1
+kind: ExternalSecret
+metadata:
+  name: example
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: tenant-vault-secret-store
+    kind: SecretStore
+  data:
+  - secretKey: secret-key-to-be-managed
+    remoteRef:
+      key: provider-key
+      property: provider-key-property
+  dataFrom:
+  - key: remote-key-in-the-provider
+```
+
+## Cluster Secret Store
+
+A cluster secret store is a global, cluster-wide `SecretStore` that can be referenced from all namespaces. It is used for secrets that need to be distributed across all namespaces.

content/external-secret-operator/workflow.md

@@ -0,0 +1,31 @@
+# External Secret Operator Workflow
+
+This diagram explains how Multi Tenant Operator works together with Vault and External Secrets Operator:
+
+![External-Secrets-workflow](./images/external-secret-operator.png)
+
+## Workflow
+
+### Step 1
+
+In `externalSecret` we define details of secrets available in Vault and secret store that reference Vault connection and authentication details.
+
+### Step 2
+
+Secret Store `tenant-vault-secret-store` is already created in each namespace by Multi Tenant Operator templates. It refers to service account `tenant-vault-access` for authentication. Secret Store also refers to Vault `role` created with the same name as namespace name by Multi Tenant Operator.
+
+### Step 3
+
+Service account `tenant-vault-access` being referred by `SecretStore` is already created by Multi Tenant Operator templates. This service account has the `stakater.com/vault-access: 'true'` label, which is used to bound it with the Vault `role` by Multi Tenant Operator. To learn how Multi Tenant Operator authenticates with Vault, see [Vault Multitenancy](https://docs.stakater.com/mto/vault-multitenancy.html).
+
+### Step 4
+
+Vault verifies if the defined service account has access to `role` and `role` has an attached `policy` that grants access to requested path.
+
+### Step 5
+
+After authentication is successful, external secrets get data from the path requested from Vault.
+
+### Step 6
+
+Kubernetes secret is created from the values stored in Vault.

content/index.md

@@ -0,0 +1,25 @@
+# Stakater secrets management
+
+Secrets management is a fundamental aspect of complying with security certifications, for example ISO 27001 A.8.1 specifies the need for inventory of assets and ownership of assets.
+
+Stakater offers a number of services for managing secrets in Kubernetes using HashiCorp Vault. The right offer for your needs depends on your current situation.
+
+## Secrets management assessment
+
+With a secret management assessment, Stakater will assess your current secret management architecture and give you all the insights and knowledge on how to bring it onto the next level.
+
+## Architecture and design
+
+To benefit from everything HashiCorp Vault has to offer and how it best suits your needs, Stakater will lead you through the design of the best fitting solution. Stakater investigates what authentication or authorization secrets you want to keep safe, what policies are relevant to you and how to integrate Vault into your workflows.
+
+## Prototyping
+
+Stakater can perform prototyping to test the secrets environment you have built yourself or help you with the initial implementation, configuration, integration and testing.
+
+## Integration
+
+If you have an existing initial concept of your HashiCorp Vault platform, Stakater can help to deploy, configure and integrate Vault to achieve production readiness using cloud native and GitOps methods and HashiCorp best practices.
+
+## Managed service
+
+If you rather not manage HashiCorp Vault yourself, Stakater can manage it for you through our [fully managed cloud offering](./managed-service/offer.md). Stakater Vault allows your organization to get up and running quickly, with the platform providing the reliability and security needed so you do not have to manage Vault yourself. Stakater Vault enables you to manage secrets and protect sensitive data with a lower total cost of ownership compared to managing your own instance.

content/introduction.md

@@ -0,0 +1,68 @@
+# Introduction to Secrets
+
+Kubernetes Secrets let you store and manage sensitive information, such as passwords, OAuth tokens, and ssh keys. Storing confidential information in a secret is safer and more flexible than putting it verbatim in a pod definition or in a container image.
+
+Secrets can contain user credentials required by pods to access a database. For example, a database connection string consists of a username and password. You can store the username in a file `./username.txt` and the password in a file `./password.txt` on your local machine.
+
+```sh
+# Create files needed for the rest of the example
+echo -n 'admin' > ./username.txt
+echo -n '1f2d1e2e67df' > ./password.txt
+```
+
+```sh
+kubectl create secret generic db-user-pass --from-file=./username.txt --from-file=./password.txt
+```
+
+## Kubernetes secrets
+
+There are two ways for storing secrets in Kubernetes resources:
+
+* Base64 decode your values and create a secret:
+
+    ```yaml
+    apiVersion: v1
+    kind: Secret
+    metadata:
+      name: mysecret
+    type: Opaque
+    data:
+      config.yaml: |-
+        apiUrl: "YXBpLmNvbQo="  # base64 for api.com
+        username: YWRtaW4K      # base64 for admin
+        password: cGFzc3dvcmQK  # base64 for password
+    ```
+
+* Use string data with literal values to create secret:
+
+    ```yaml
+    apiVersion: v1
+    kind: Secret
+    metadata:
+      name: mysecret
+    type: Opaque
+    stringData:
+      config.yaml: |-
+        apiUrl: "https://my.api.com/api/v1"
+        username: admin
+        password: password
+    ```
+
+## Limitations of Kubernetes secrets
+
+1. They are not encrypted at rest
+1. By default, cluster admins can see all the secrets of all the tenants
+1. When in use (i.e. mounted as `tempfs` in the node that runs the pod that is using them), they can be seen by a node administrator
+1. When in use, they can be seen by anyone who has the ability to remote shell into the container
+1. Can not store Kubernetes secrets in Git repo as anyone can decode them
+
+So to handle this case, we need some other tool to handle this.
+
+SAAP offers two different managed solutions for consuming secrets in more secure fashion:
+
+1. [Vault](vault.md)
+1. [Sealed Secrets](sealed-secrets.md)
+
+## Stakater Secrets Services
+
+Stakater offers a complete range of [services for secrets management](index.md).