[v1.3] release and doc improvements (#141)

**Which issue is resolved by this Pull Request:** Resolves #129 **Testing:** - Cloning the branch works By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
awslabs · Mar 18, 2022 · 57f7b32 · 57f7b32
1 parent 5b4408c
commit 57f7b32
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 23 deletions.
diff --git a/distributions/aws/examples/README.md b/distributions/aws/examples/README.md
@@ -82,4 +82,29 @@ kubectl delete cronjob -n kubeflow aws-kubeflow-telemetry
 The telemetry data we collect is in accordance with AWS data privacy policies. For more information, see the following:
 
 * [AWS Service Terms](https://aws.amazon.com/service-terms/)
-* [Data Privacy](https://aws.amazon.com/compliance/data-privacy-faq/)
+* [Data Privacy](https://aws.amazon.com/compliance/data-privacy-faq/)
+
+
+## Releases and Versioning
+
+This repository was created for the development of Kubeflow on AWS as described in the [Kubeflow distributions guidelines](https://github.com/kubeflow/community/blob/master/proposals/kubeflow-distributions.md). 
+
+#### v1.3.1
+
+Although the distribution manifests are hosted in this repository, many of the overlays and configuration files in this repository have a dependency on the manifests published by the Kubeflow community in the [kubeflow/manifests](https://github.com/kubeflow/manifests) repository. Hence, the AWS distribution of Kubeflow for v1.3.1 was developed on a [fork](https://github.com/awslabs/kubeflow-manifests/tree/v1.3-branch) of the `v1.3-branch` of the `kubeflow/manifests` repository. This presented several challenges for ongoing maintenance as described in [Issue #76](https://github.com/awslabs/kubeflow-manifests/issues/76). 
+
+#### v1.4+
+
+Starting with Kubeflow v1.4, the development of the AWS distribution of Kubeflow is done on the [`main`](https://github.com/awslabs/kubeflow-manifests/tree/main) branch. The `main` branch contains only the delta from the released manifests in the `kubeflow/manifests` repository and additional components required for the AWS distribution.
+
+### Versioning
+
+Kubeflow on AWS releases are built on top of Kubeflow releases and therefore use the following naming convention: `{KUBEFLOW_RELEASE_VERSION}-aws-b{BUILD_NUMBER}`.
+
+* Ex: Kubeflow v1.3.1 on AWS version 1.0.0 will have the version `v1.3.1-aws-b1.0.0`.
+
+`KUBEFLOW_RELEASE_VERSION` refers to [Kubeflow's released version](https://github.com/kubeflow/manifests/releases) and `BUILD_NUMBER` refers to the AWS build for that Kubeflow version. `BUILD_NUMBER` uses [semantic versioning](https://semver.org/) (SemVer) to indicate whether changes included in a particular release introduce features or bug fixes and whether or not features break backwards compatibility.
+
+### Releases
+
+When a version of Kubeflow on AWS is released, a Git tag with the naming convention `{KUBEFLOW_RELEASE_VERSION}-aws-b{BUILD_NUMBER}` is created. These releases can be found in the Kubeflow on AWS repository [releases](https://github.com/awslabs/kubeflow-manifests/releases) section.
diff --git a/distributions/aws/examples/cognito/README.md b/distributions/aws/examples/cognito/README.md
@@ -32,16 +32,18 @@ This guide assumes that you have:
         --nodes-max 10 \
         --managed
         ```
-1. AWS IAM permissions to create roles and attach policies to roles.
 
-1. Clone the `awslabs/kubeflow-manifest` repo and checkout release branch.
-    1. ```
-        git clone https://github.com/awslabs/kubeflow-manifests.git
-        cd kubeflow-manifests
-        git checkout v1.3-branch
-        ```
+1. Clone the `awslabs/kubeflow-manifest` repo and checkout a release.
+    1. Substitute the value for `AWS_RELEASE_VERSION`(e.g. v1.3.1-b1.0.0). Read more about [releases and versioning](../README.md#releases-and-versioning) policy if you are unsure about what the value of `AWS_RELEASE_VERSION` should be.
+        1. ```
+            export AWS_RELEASE_VERSION=<>
+            git clone https://github.com/awslabs/kubeflow-manifests.git
+            cd kubeflow-manifests
+            git checkout ${AWS_RELEASE_VERSION}
+            ```
 
-**Tip:** The following sections in this guide walks you through each step for setting up domain, certificates and Cognito userpool and is good for a new user to understand the setup. If you prefer a automated setup for setting up these pre-requisites for deploying Kubeflow with Cognito, follow this [README](./README-automated.md)
+## (Optional) Automated setup
+The rest of the sections in this guide walks you through each step for setting up domain, certificates and Cognito userpool using AWS Console and is good for a new user to understand the design and details. If you prefer to use automated scripts and avoid human error for setting up the resources for deploying Kubeflow with Cognito, follow this [README](./README-automated.md) instead.
 
 ## 1.0 Custom domain
 

diff --git a/distributions/aws/examples/rds-s3/README.md b/distributions/aws/examples/rds-s3/README.md
@@ -23,13 +23,14 @@ The following steps show how to configure and deploy Kubeflow with supported AWS
      - :warning: Kubeflow 1.3.0 is not compatible with the latest versions of of kustomize 4.x. This is due to changes in the order resources are sorted and printed. Please see [kubernetes-sigs/kustomize#3794](https://github.com/kubernetes-sigs/kustomize/issues/3794) and [kubeflow/manifests#1797](https://github.com/kubeflow/manifests/issues/1797). We know this is not ideal and are working with the upstream kustomize team to add support for the latest versions of kustomize as soon as we can.
 
 
-2. Clone the repo and checkout the release branch
-
-```
-git clone https://github.com/awslabs/kubeflow-manifests.git
-cd kubeflow-manifests
-git checkout v1.3-branch
-```
+1. Clone the `awslabs/kubeflow-manifest` repo and checkout a release.
+    1. Substitute the value for `AWS_RELEASE_VERSION`(e.g. v1.3.1-b1.0.0). Read more about [releases and versioning](../README.md#releases-and-versioning) policy if you are unsure about what the value of `AWS_RELEASE_VERSION` should be.
+        1. ```
+            export AWS_RELEASE_VERSION=<>
+            git clone https://github.com/awslabs/kubeflow-manifests.git
+            cd kubeflow-manifests
+            git checkout ${AWS_RELEASE_VERSION}
+            ```
 
 3. Create an EKS cluster
 

diff --git a/distributions/aws/examples/vanilla/README.md b/distributions/aws/examples/vanilla/README.md
@@ -32,14 +32,15 @@ This guide assumes that you have:
         --nodes-max 10 \
         --managed
         ```
-1. AWS IAM permissions to create roles and attach policies to roles.
 
-1. Clone the `awslabs/kubeflow-manifest` repo and checkout release branch.
-    1. ```
-        git clone https://github.com/awslabs/kubeflow-manifests.git
-        cd kubeflow-manifests
-        git checkout v1.3-branch
-        ```
+1. Clone the `awslabs/kubeflow-manifest` repo and checkout a release.
+    1. Substitute the value for `AWS_RELEASE_VERSION`(e.g. v1.3.1-b1.0.0). Read more about [releases and versioning](../README.md#releases-and-versioning) policy if you are unsure about what the value of `AWS_RELEASE_VERSION` should be.
+        1. ```
+            export AWS_RELEASE_VERSION=<>
+            git clone https://github.com/awslabs/kubeflow-manifests.git
+            cd kubeflow-manifests
+            git checkout ${AWS_RELEASE_VERSION}
+            ```
 
 ### Build Manifests and Install Kubeflow