Add ability to install from release version + doc updates (#29)

* Add instructions for installing from release

* Development and instllation updates

* more updates

* add more quotes

* Add usage section

Author: Ben Du

CONTRIBUTING.md

@@ -96,7 +96,9 @@ kind delete cluster --name my-cluster
 
 ### Deploying to a cluster
 
-You must first push a Docker image containing the changes to a Docker repository like ECR.
+You must first push a Docker image containing the changes to a Docker repository like ECR, Github packages, or DockerHub. The repo is configured to use Github Actions to automatically publish the docker image upon push to `main` branch. The image URI will be `ghcr.io/[Your forked repo name here]` You can enable this for forked repos by enabling Github actions on your forked repo in the "Actions" tab of forked repo.
+
+If you are deploying to cluster using kustomize templates from the `config` directory, you will need to override the image URI away from `ghcr.io/aws/aws-cloud-map-mcs-controller-for-k8s` in order to use your own docker images.
 
 ### Build and push docker image to ECR
 

README.md

@@ -10,15 +10,79 @@
 ## Introduction
 AWS Cloud Map multi-cluster service discovery for Kubernetes (K8s) is a controller that implements existing multi-cluster services API that allows services to communicate across multiple clusters. The implementation relies on [AWS Cloud Map](https://aws.amazon.com/cloud-map/) for enabling cross-cluster service discovery.
 
+## Usage
+> ⚠ **There must exist network connectivity (i.e. VPC peering, security group rules, ACLs, etc.) between clusters**: Undefined behavior may occur if controller is set up without network connectivity between clusters.
+
+### Setup clusters
+
+First, install the controller with latest release on at least 2 AWS EKS clusters. Nodes must have sufficient IAM permissions to perform CloudMap operations.
+
+```sh
+kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release"
+```
+
+> 📌 See [Releases](#Releases) section for details on how to install other versions.
+
+### Export services
+
+Then assuming you already have a Service installed, apply a `ServiceExport` yaml to the cluster in which you want to export a service. This can be done for each service you want to export.
+
+```yaml
+kind: ServiceExport
+apiVersion: multicluster.x-k8s.io/v1alpha1
+metadata:
+  namespace: [Your service namespace here]
+  name: [Your service name]
+```
+
+**Example:** This will export a service with name *my-amazing-service* in namespace *hello*
+```yaml
+kind: ServiceExport
+apiVersion: multicluster.x-k8s.io/v1alpha1
+metadata:
+  namespace: hello
+  name: my-amazing-service
+```
+
+*See the `samples` directory for a set of example yaml files to set up a service and export it. To apply the sample files run*
+```sh
+kubectl create namespace demo
+kubectl apply -f https://raw.githubusercontent.com/aws/aws-cloud-map-mcs-controller-for-k8s/main/samples/demo-deployment.yaml
+kubectl apply -f https://raw.githubusercontent.com/aws/aws-cloud-map-mcs-controller-for-k8s/main/samples/demo-service.yaml
+kubectl apply -f https://raw.githubusercontent.com/aws/aws-cloud-map-mcs-controller-for-k8s/main/samples/demo-export.yaml
+```
+
+### Import services
+
+In your other cluster, the controller will automatically sync services registered in AWS CloudMap by applying the appropriate `ServiceImport`. To list them all, run
+```sh
+kubectl get ServiceImport -A
+```
+
 ## Releases
 
 AWS Cloud Map MCS Controller for K8s adheres to the [SemVer](https://semver.org/) specification. Each release updates the major version tag (eg. `vX`), a major/minor version tag (eg. `vX.Y`) and a major/minor/patch version tag (eg. `vX.Y.Z`). To see a full list of all releases, refer to our [Github releases page](https://github.com/aws/aws-cloud-map-mcs-controller-for-k8s/releases).
 
+To install from a release run
+```sh
+kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release[?ref=*git version tag*]"
+```
+
+Example to install latest release
+```sh
+kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release"
+```
+
+Example to install v0.1.0
+```sh
+kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_release?ref=v0.1.0"
+```
+
 We also maintain a `latest` tag, which is updated to stay in line with the `main` branch. We **do not** recommend installing this on any production cluster, as any new major versions updated on the `main` branch will introduce breaking changes.
 
 To install from `latest` tag run
 ```sh
-kubectl apply -k github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_latest
+kubectl apply -k "github.com/aws/aws-cloud-map-mcs-controller-for-k8s/config/controller_install_latest"
 ```
 
 ## Contributing

config/controller_install_release/kustomization.yaml

@@ -0,0 +1,7 @@
+bases:
+- ../default
+
+images:
+- name: controller
+  newName: ghcr.io/aws/aws-cloud-map-mcs-controller-for-k8s
+  newTag: v0.1.0