Docs: Recipe Overview - details usage and S3 behavior

docs/krp.md

@@ -48,40 +48,14 @@ of events.  Second, the scope of asynchrony can be the source of failed
 dependencies resulting in backoff retry loops which can violate the application
 Recovery Time Objective (RTO).  Restoring resources in a prescribed order can
 avoid both of these problems.  So the Ramen VRG provides a mechanism to support
-capturing and restoring resources in a prescribed order.
-
-## An Example Kubernetes Resource Protection Specification
+capturing and restoring resources in a prescribed order: through a
+[Recipe](recipe_overview.md). When a prescribed order is not required,
+Kubernetes resources can be captured and restored through the VRG by enabling
+KubeObjectProtection:
 
 ```yaml
-    spec:
-        kubeObjectProtection:
-            # backup section
-            captureInterval: 30m
-            captureOrder:
-                - name: config  # backup Names should be unique
-                    includedResources: ["ConfigMap", "Secret"]
-                - name: custom
-                    includedResources: ["sample1.myapp.mycompany.com", "sample.myapp.mycompany.com", "sample3.myapp.mycompany.com"]
-                    labelSelector: "myAppPersist"
-                    # includeClusterResources: false # by default
-                - name: deployments
-                    includedResources: ["Deployment"]
-                - name: everything
-                    includeClusterResources: true
-                    excludedResources: [""]  # include everything with no history, even resources in other backups
-            # restore section
-            recoverOrder:
-                - backupName: config # API server required matching to backup struct
-                    includedResources: ["ConfigMap", "Secret"]
-                - backupName: custom
-                    includedResources: ["sample1.myapp.mycompany.com", "sample2.myapp.mycompany.com", "sample3.myapp.mycompany.com"]
-                    # labelSelector: "" # intentionally omitted - don't require label match
-                    # includeClusterResources: false # by default
-                - backupName: deployments
-                    includedResources: ["Deployment"]
-                - backupName: everything
-                    includeClusterResources: true
-                    excludedResources: ["ConfigMap", "Secret", "Deployment", "sample1.myapp.mycompany.com", "sample2.myapp.mycompany.com", "sample3.myapp.mycompany.com"]  # don't restore resources we've already restored
+spec:
+  kubeObjectProtection: {}
 ```
 
 ## Explanation of the Capture and Recovery Specifications in the VRG
@@ -97,26 +71,3 @@ part of disaster protection.  This is accomplished through the
 kubeObjectProtection section of the VRG spec.  If kubeObjectProtection is not
 included in a VRG, then Kubernetes resources are not protected as part of the
 VRG disaster protection.
-
-The kubeObjectProtection section contains two sub-sections, captureOrder and
-recoverOrder.  This captureOrder section provides instructions on how to backup
-a namespaces Kubernetes resources.  The recoverOrder section provides
-instructions on how to recover a namespaces Kubernetes resources after a
-disaster.  This implies that the backup and recover order can be different and
-don't need to include all the same resources.  Each of the captureOrder and
-recoverOrder sections contain a list of resource instructions.  Each item in the
-list is acted upon even if it duplicates work done by other items in the list.
-So care should be taken to avoid duplication within either the backup or recover
-lists so that the best RPO and RTO are achieved.  The list items must meet the
-following requirements.  If the requirements are not met, then the operation of
-the lists is undefined.
-
-1. The name of each item in the captureOrder list must be unique
-1. The backupName of each item in the recoverOrder list much match a name in the
- recoverOrder list
-1. A labelSelector in a list item only applies to that item in the list
-1. If a list item contains multiple labelSelectors then any resource that
- matches either label selector is operated upon
-1. includeClusterResources in a list item only applies to that item in the list
-1. Each list item can contain either an includedResources section or an
- excludedResources section, but not both

docs/krp_install.md

@@ -0,0 +1,124 @@
+# Kube Resource Protection / Recipe Installation
+
+## Requirements
+
+To enable Kube Resource Protection, a system must have access to:
+
+1. S3 store (e.g. Minio/Noobaa) installed and configured
+1. S3 store credentials
+1. Velero/OADP installed and configured
+1. Velero credentials
+
+## Setup
+
+### Ramen ConfigMap
+
+The Ramen ConfigMap is stored in the `ramen-system` namespace (or `openshift-dr-system`
+on OpenShift) with name `ramen-dr-cluster-operator-config`. This ConfigMap contains
+s3 profile information like this:
+
+```yaml
+data:
+  ramen_manager_config.yaml: |
+    s3StoreProfiles:
+    - s3ProfileName: minio-cluster1
+      s3Bucket: velero
+      s3CompatibleEndpoint: http://192.168.39.136:30000
+      s3Region: us-east-1
+      s3SecretRef:
+        name: minio-s3
+      VeleroNamespaceSecretKeyRef:
+        key: cloud-credentials
+        name: cloud
+```
+
+For every s3 profile, two Secrets will need to be created: one with s3 credentials,
+one with Velero/OADP credentials. This means for two S3 profiles, four Secrets are
+required, and so on.
+
+### S3 Secret setup
+
+How to set up the S3 Secret:
+
+1. Name: needs to match Ramen ConfigMap's s3StoreProfile `s3SecretRef.name`. From
+  the example above, this Secret is named `minio-s3`.
+1. Namespace: the Secret needs to be in the same namespace as the Ramen operator.
+  This will be `ramen-system` or `openshift-dr-system` in most cases. If there's
+  any doubt about this, search for the deployment called `ramen-dr-cluster-operator`,
+  and use that Namespace.
+1. Contents: `data` should contain two keys: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`,
+  both of which are base64 encoded. If the s3 login is `minio`, the base64 encoding
+  is `bWluaW8=`. If the s3 password is `minio123`, the base64 encoding is `bWluaW8xMjM=`.
+  Here is an example file showing all of these in use:
+
+```yaml
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: minio-s3  # match to Ramen ConfigMap's s3Profile.s3SecretRef.name
+  namespace: ramen-system  # must be in the same namespace as Ramen operator
+type: Opaque
+data:
+  AWS_ACCESS_KEY_ID: bWluaW8=
+  AWS_SECRET_ACCESS_KEY: bWluaW8xMjM=
+```
+
+### Velero Secret setup
+
+How to set up the Velero secret:
+
+1. Name: needs to match Ramen ConfigMap's `veleroNamespaceSecretKeyRef.name`. In
+  the example above, this Secret is named `cloud`.
+1. Namespace: the Secret needs to be in the same namespace as the Ramen operator.
+  This will be `ramen-system` or `openshift-dr-system` in most cases.
+1. Contents: data should contain one key, and that name should match the Ramen ConfigMap's
+  `veleroNamespaceSecretKeyRef.key` value. In the example above, this is `cloud-credentials`.
+  The contents of this key are base64 encoded into a single value, but the format
+  of the plain text is:
+
+Filename=`cloud-credentials`
+
+```
+[default]
+aws_access_key_id = minioUser
+aws_secret_access_key = minioLogin
+```
+
+To create a Secret in the Ramen namespace with `cloud-credentials` as the key,
+use this command:
+
+`kubectl create secret generic cloud --from-file=cloud-credentials -n ramen-system`
+
+Using `kubectl get secret/cloud -n ramen-system -o yaml` to examine the contents:
+
+```yaml
+apiVersion: v1
+data:
+  cloud_credentials: W2RlZmF1bHRdCmF3c19hY2Nlc3Nfa2V5X2lkID0gbWluaW9Vc2VyCmF3c19zZWNyZXRfYWNjZXNzX2tleSA9IG1pbmlvTG9naW4KCg==
+kind: Secret
+metadata:
+  creationTimestamp: "2023-06-12T18:39:12Z"
+  name: cloud  # match to Ramen ConfigMap's s3Profile.veleroNamespaceSecretKeyRef.name
+  namespace: ramen-system  # must be in the same namespace as Ramen operator
+  resourceVersion: "23042901"
+  uid: 860ce0ae-d428-4a84-81d8-349544f92049
+type: Opaque
+```
+
+Now Ramen should be able to access Velero.
+
+### Using an alternate Velero namespace
+
+By default, Ramen expects Velero to be installed in the `velero` namespace. If
+Velero is installed in another namespace, it is necessary to define this in the
+Ramen ConfigMap in the `kubeObjectProtection.veleroNamespaceName` field. For a
+system that uses OADP installed in the `openshift-adp` Namespace, the Ramen ConfigMap
+setting would look like this:
+
+```yaml
+data:
+  ramen_manager_config.yaml: |
+    kubeObjectProtection:
+      veleroNamespaceName: openshift-adp
+```