Create Cloud Map documentation

asimpleidea · asimpleidea · commit 8dfbb31b86d1 · 2021-12-01T09:55:18.000+01:00
This adds guides about Cloud Map and updates some existing ones by
including Cloud Map settings/data.

Signed-off-by: Elis Lulja &lt;elulja@cisco.com&gt;
diff --git a/README.md b/README.md
@@ -49,9 +49,15 @@ If you want to quickly see how CN-WAN Operator works, you can follow this simple
 
 ### Google Service Directory
 
-* [Quickstart with service directory](./docs/gcp_service_directory/quickstart.md)
+* [Quickstart with Service Directory](./docs/gcp_service_directory/quickstart.md)
 * [Concepts](./docs/gcp_service_directory/concepts.md)
-* [Configure CN-Operator with service directory](./docs/gcp_service_directory/configure_with_operator.md)
+* [Configure CN-Operator with Service Directory](./docs/gcp_service_directory/configure_with_operator.md)
+
+### AWS Cloud Map
+
+* [Quickstart with Cloud Map](./docs/aws_cloud_map/quickstart.md)
+* [Concepts](./docs/aws_cloud_map/concepts.md)
+* [Configure CN-Operator with Cloud Map](./docs/aws_cloud_map/operator_configuration.md)
 
 ## Contributing
 
diff --git a/docs/aws_cloud_map/concepts.md b/docs/aws_cloud_map/concepts.md
@@ -0,0 +1,12 @@
+# Concepts
+
+## AWS Cloud Map
+
+AWS Cloud Map is an example of a service registry and it groups resources as *Namespace*, *Service* and *Instance*.
+
+For more information about Cloud Map, you can refer to its [official website](https://aws.amazon.com/cloud-map/).
+
+Useful links:
+
+* A [quickstart](./quickstart.md) for Cloud Map and CN-WAN Operator
+* A [guide](./operator_configuration.md) to correctly configure CN-WAN Operator with Cloud Map
diff --git a/docs/aws_cloud_map/operator_configuration.md b/docs/aws_cloud_map/operator_configuration.md
@@ -0,0 +1,64 @@
+# Configure CN-WAN Operator with AWS Cloud Map
+
+## Settings format
+
+The included directory `artifacts/settings` contains a `settings.yaml` for you to modify with the appropriate values.
+
+For your convenience, here is how the settings for the CN-WAN Operator looks like:
+
+```yaml
+watchNamespacesByDefault: false
+serviceAnnotations: []
+serviceRegistry:
+  etcd:
+    prefix: <prefix>
+    authentication: <your-authentication-type>
+    endpoints:
+    - host: <host-1>
+      port: <port-1>
+    - host: <host-2>
+      port: <port-2>
+  gcpServiceDirectory:
+    defaultRegion: <region>
+    projectID: <project>
+  awsCloudMap:
+    defaultRegion: <region>
+cloudMetadata:
+  network: auto
+  subNetwork: auto
+```
+
+We will only cover Cloud Map settings here, so you can go ahead and remove some settings:
+
+```yaml
+watchNamespacesByDefault: false
+serviceAnnotations: []
+serviceRegistry:
+  awsCloudMap:
+    defaultRegion: <region>
+```
+
+`namespace` and `service` settings are covered in the [main documentation](../configuration.md). Let's now only focus on `serviceRegistry` options.
+
+## Cloud Map settings
+
+### Default region
+
+This is the [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where you want the CN-WAN Operator to put objects into. You should choose a region as close as possible to your cluster or the end user of Cloud Map.
+
+## Full example
+
+### Example 1
+
+In this example, you are telling the CN-WAN Operator:
+
+* to use `us-west-2` as default region
+
+Here is the settings example - we omit `namespace` and `service` settings for brevity:
+
+```yaml
+namespace: ...
+service: ...
+  awsCloudMap:
+    defaultRegion: us-west-2
+```
diff --git a/docs/aws_cloud_map/quickstart.md b/docs/aws_cloud_map/quickstart.md
@@ -0,0 +1,168 @@
+# Quickstart
+
+To run this, make sure you have:
+
+* Access to a Kubernetes cluster running at least version `1.11.3` with support for [LoadBalancer](./concepts.md#supported-service-types) type of services and that can perform outbound HTTP/S requests successfully.
+  * You can even try with [KinD](https://kind.sigs.k8s.io/) or [Minikube](https://kubernetes.io/docs/setup/learning-environment/minikube/), but make sure *Load Balancer*s work.
+* [Kubectl 1.11.3+](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+* An AWS account
+* AWS Credentials file
+
+Finally, [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) needs to be properly set up.
+
+## Let's go
+
+### 1 - Clone the project
+
+```bash
+git clone https://github.com/CloudNativeSDWAN/cnwan-operator.git
+cd ./cnwan-operator
+```
+
+### 2 - Deploy a test service
+
+We will suppose you are deploying an application on your cluster where your employees can log in and watch training videos.
+
+Run this to deploy a new namespace and a service in that namespace:
+
+```bash
+cat <<EOF | kubectl create -f -
+kind: Namespace
+apiVersion: v1
+metadata:
+    name: training-app-namespace
+    labels:
+        purpose: "test"
+        operator.cnwan.io/watch: "enabled"
+---
+kind: Service
+apiVersion: v1
+metadata:
+    name: web-training
+    namespace: training-app-namespace
+    labels:
+        app: "training"
+    annotations:
+        version: "2.1"
+        traffic-profile: "standard"
+spec:
+    ports:
+        - name: port80
+          protocol: TCP
+          port: 80
+          targetPort: 8080
+    selector:
+        app: "training"
+    type: LoadBalancer
+EOF
+```
+
+Please notice that the namespace has this label: `operator.cnwan.io/watch: enabled` which instructs the operator to watch events occurring in this namespace. Also notice that the service has annotations that will be registered as [metadata](./concepts.md#metadata):
+
+```yaml
+annotations:
+   traffic-profile: standard
+```
+
+Now verify that the namespace is there:
+
+```bash
+kubectl get ns
+
+NAME                   STATUS   AGE
+training-app-namespace          Active   1h
+```
+
+Verify that the service is there and has an IP:
+
+```bash
+kubectl get service -n training-app-namespace
+
+NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP    PORT(S)                       AGE
+web-training           LoadBalancer   10.11.12.13      20.21.22.23    80:32058/TCP                  1h
+```
+
+If you see `<none>` or `<pending>` under `EXTERNAL-IP` you either have to wait to see an IP there or your cluster doesn't support [LoadBalancer](./concepts.md#supported-service-types).
+
+It doesn't really matter that there is no pod backing this service for now, as this is just a test. Of course, in a real world scenario you should make sure a pod is there.
+
+### 3 - Provide the credentials file
+
+Navigate to the root directory and place your credentials file to `artifacts/secrets`, with name `credentials`.
+
+### 4 - Provide settings
+
+From the root directory navigate to `artifacts/settings` and modify the file `settings.yaml` to look like this - please provide appropriate values in place of `<gcloud-project>` and `<gcloud-region>`:
+
+```yaml
+watchNamespacesByDefault: false
+serviceAnnotations:
+  - traffic-profile
+  - version
+serviceRegistry:
+  awsCloudMap:
+    defaultRegion: <region>
+```
+
+Please notice the values inside `annotations`:
+
+```yaml
+  annotations:
+  - traffic-profile
+  - version
+```
+
+This means that the operator will register `traffic-profile` as tags if it finds it among a [service's annotations list](./concepts.md#allowed-annotations).
+
+### 5 - Deploy the operator
+
+From the root directory of the project, execute
+
+```bash
+./scripts/deploy.sh cloudmap
+```
+
+### 6 - See it on Cloud Map
+
+Now, log in to Cloud Map from the AWS console and after some time you will see a namespace that has the same name as the Kubernetes namespace where that service was found in.
+
+If you click on it, you will see a service: its tags contain `traffic-profile: standard`. It will also contain an instance with data about the port and the address.
+
+### 7 - Update metadata
+
+Now you're basically done, but you can follow these additional steps to see more of the operator in action.
+
+Suppose you made a mistake: this is a training application where your employees will follow video tutorials and therefore, its kind of traffic - or, *profile*, must be `video`.
+
+Execute:
+
+```bash
+kubectl annotate service web-training traffic-profile=video --overwrite -n training-app-namespace
+```
+
+The operator has updated the tags in Cloud Map accordingly.
+
+### 8 - Add new metadata
+
+Suppose you have a CI/CD pipeline that for each PR builds a container with a new tag. Also, it updates the service that serves the pods running that container by specifying the new version. Today, you will be that pipeline:
+
+```bash
+kubectl annotate service web-training version=2.2 -n training-app-namespace --overwrite
+```
+
+Once again, log in to Cloud Map and see how the tags for that service have changed accordingly.
+
+## Where to go from here
+
+Well, that's it for a quickstart. Now we encourage you to learn more about CN-WAN Operator by taking a look at the [docs](./).
+
+Also, make sure you read the [official documentation of CN-WAN](https://github.com/CloudNativeSDWAN/cnwan-docs) to learn how you can apply this simple quickstart to a real world scenario.
+
+## Clean up
+
+From the root directory of the project, run
+
+```bash
+./scripts/remove.sh
+kubectl delete ns training-app-namespace
+```
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -31,6 +31,8 @@ serviceRegistry:
   gcpServiceDirectory:
     defaultRegion: <region>
     projectID: <project>
+  awsCloudMap:
+    defaultRegion: <region>
 cloudMetadata:
   network: auto
   subNetwork: auto
@@ -120,11 +122,13 @@ cloudMetadata:
   subNetwork: auto
 ```
 
-and the Operator will try to detect such information on its own. You can remove a field, e.g. `subNetwork`, from the settings if you don't want that to be registered.
+and the Operator will try to detect such information on its own. Note that automatic feature is only supported for *GKE* and for the other platforms you will have to write that information manually until they will be supported as well.
+
+You can remove a field, e.g. `subNetwork`, from the settings if you don't want that to be registered.
 
 These values will be registered on a service metadata as:
 
-```text
+```yaml
 cnwan.io/network: <name-or-id>
 cnwan.io/sub-network: <name-or-id>
 ```
@@ -135,10 +139,11 @@ Additionally, `cnwan.io/platform: <name>` will also be included if the operator
 
 Under `serviceRegistry` you define which service registry to use and how the operator should connect to it or manage its objects.
 
-As of now, only one of `etcd` or `gcpServiceDirectory` is allowed, and therefore you should remove the one that you don't use. Please follow one of the following guides to learn how to configure the Operator with the chosen service registry:
+As of now, only one of `etcd`, `gcpServiceDirectory` or `awsCloudMap` is allowed, and therefore you should remove the one that you don't use. Please follow one of the following guides to learn how to configure the Operator with the chosen service registry:
 
 * [etcd](./etcd/operator_configuration.md)
-* [service directory](./gcp_service_directory/configure_with_operator.md)
+* [Service Directory](./gcp_service_directory/configure_with_operator.md)
+* [Cloud Map](./aws_cloud_map/operator_configuration.md)
 
 ## Deploy settings
 
diff --git a/docs/install.md b/docs/install.md
@@ -15,12 +15,15 @@ You need to have the following:
 
 Depending on the service registry you chose:
 
-* For Google Service Directory:
-  * a Project in [Google Cloud](https://console.cloud.google.com/) with [Service Directory](https://cloud.google.com/service-directory) enabled
-  * a [Google Cloud Service Account](https://cloud.google.com/iam/docs/service-accounts) with at least role `roles/servicedirectory.editor`.
 * For etcd:
   * a working and reachable etcd cluster
   * optional: user credentials for etcd
+* For Google Service Directory:
+  * a Project in [Google Cloud](https://console.cloud.google.com/) with [Service Directory](https://cloud.google.com/service-directory) enabled
+  * a [Google Cloud Service Account](https://cloud.google.com/iam/docs/service-accounts) with at least role `roles/servicedirectory.editor`.
+* For AWS Cloud Map:
+  * a AWS Account
+  * AWS credentials. Make sure you read AWS documentation to know how to get credentials, for example [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html), but we encourage you to do some research the documentation on your own, as there are many ways to get them.
 
 ### Software
 
@@ -47,7 +50,7 @@ Before deploying the operator you will need to configure it.
 
 ### Settings
 
-Modify the file `artifacts/deploy/settings/settings.yaml` with the appropriate values. If you haven't already, please read [Configuration](./configuration.md) to learn how to do this.
+Modify the file `artifacts/settings/settings.yaml` with the appropriate values. If you haven't already, please read [Configuration](./configuration.md) to learn how to do this.
 
 ## Deploy
 
@@ -58,7 +61,7 @@ Before continuing, if you also have other files that you want to be deployed, yo
 To deploy the operator with the provided script, you will have to execute `deploy.sh` as such:
 
 ```bash
-./scripts/deploy.sh etcd|servicedirectory
+./scripts/deploy.sh etcd|servicedirectory|cloudmap
 ```
 
 If you want to use your own image, you'll need to provide `--image` flag, for example:
@@ -84,14 +87,28 @@ From the root directory of the project, execute
 
 ### With Google Service Directory
 
-Place your Google account in `deploy/settings` and rename it as `gcloud-credentials.json`. Therefore, your `deploy/settings` will contain `settings.yaml` and `gcloud-credentials.json`.
+Place your Google service account in `artifacts/secrets` and rename it as `gcloud-credentials.json`.
 
 Now run
 
 ```bash
 ./scripts/deploy.sh servicedirectory
 ```
 
+or you can provide the file via `--service-account`.
+
+### With AWS Cloud Map
+
+Place your AWS credentials file `artifacts/secrets` and rename it as `credentials`.
+
+Now run
+
+```bash
+./scripts/deploy.sh cloudmap
+```
+
+or you can provide the file via `--credentials`
+
 ## Remove
 
 To remove the operator, execute:
diff --git a/docs/service_registry.md b/docs/service_registry.md
@@ -30,7 +30,7 @@ Which one you choose depends on different factors, including:
 
 and so on.
 
-As we said on the main documentation, the CN-WAN Operator currently supports *Google Service Directory* and *etcd*.
+As we said on the main documentation, the CN-WAN Operator currently supports *Google Service Directory*, *etcd* and *AWS Cloud Map*.
 
 ## Objects
 
