Update aws docs for 0.6 release (kubeflow#1030)

* Update aws docs for 0.6 release * Address code review feedbacks * Update indents to render markdown * Remove shell in code blocks * Fix indent issue * Make existing cluster solution more clear
numerology · Aug 9, 2019 · ca09f1f · ca09f1f
1 parent d09cecc
commit ca09f1f
Show file tree

Hide file tree

Showing 4 changed files with 127 additions and 120 deletions.
diff --git a/content/docs/aws/authentication.md b/content/docs/aws/authentication.md
@@ -8,11 +8,11 @@ This section shows the how to add TLS support and create a user pool to authenti
 
 
 ## Traffic Flow
-External Traffic → [ Ingress → Istio ingress gateway → ambassador ]
+External Traffic → [ Ingress → Istio ingress gateway → Istio virtual services ]
 
 When you generate and apply kubernetes resources, an ingress is created to manage external traffic to Kubernetes services. The AWS Appliction Load Balancer(ALB) Ingress Controller will provision an Application Load balancer for that ingress. By default, TLS and authentication are not enabled at creation time.
 
-The Kubeflow community plans to move from [Ambassador](https://www.getambassador.io/) to [Istio](https://istio.io/) to manage internal traffic (see [this issue](https://github.com/kubeflow/kubeflow/issues/2261)). Currently, [Ambassador](https://www.getambassador.io/) still plays the role of an API gateway. TLS, authentication, and authorization either can be done at the ALB or Istio layer for the AWS platform, and we plan to have Istio forward ingress traffic to the Istio gateway and then on to Ambassador when this happens. Once receive a clear direction from the community, we will enable TLS and authentication by default.
+In Kubeflow 0.6 release, community already move from [Ambassador](https://www.getambassador.io/) to [Istio](https://istio.io/) to manage internal traffic. In AWS solution, TLS, authentication,can be done at the ALB and and authorization can be done at Istio layer.
 
 
 ## Enable TLS and Authentication
@@ -39,17 +39,24 @@ To get TLS support from the ALB Ingress Controller, you need to follow [this tut
 
 In order to authenticate and manage users for Kubeflow, let's create a user pool. You can follow these instructions here. Once a user pool created, we will have a `UserPoolId`, a Cognito Domain name, and a Cognito Pool Arn.
 
-Before you apply k8s, you can go into ${KUBEFLOW_SRC}/${KFAPP}/ks_app,
+Before you `generate all -V`, please update Cognito spec in `app.yaml` like this,
 
 ```
-ks param set istio-ingress CognitoUserPoolArn arn:aws:cognito-idp:us-west-2:xxx:userpool/xxx
-ks param set istio-ingress CognitoAppClientId xxxxxx
-ks param set istio-ingress CognitoUserPoolDomain xxxx
-ks param set istio-ingress enableCognito true
-ks param set istio-ingress certArn arn:aws:acm:us-west-2:xxx:certificate/xxxe4031c
+plugins:
+    - name: aws
+      spec:
+        auth:
+          cognito:
+            cognitoUserPoolArn: arn:aws:cognito-idp:us-west-2:xxxxx:userpool/us-west-2_xxxxxx
+            cognitoAppClientId: xxxxxbxxxxxx
+            cognitoUserPoolDomain: your-user-pool
+            certArn: arn:aws:acm:us-west-2:xxxxx:certificate/xxxxxxxxxxxxx-xxxx
+        roles:
+          - eksctl-kubeflow-aws-nodegroup-ng-a2-NodeInstanceRole-xxxxx
+        region: us-west-2
 ```
 
-After you finish the TLS and Authentication configuration, then you can run `${KUBEFLOW_SRC}/${KFAPP}/scripts/kfctl.sh apply k8s`.
+After you finish the TLS and Authentication configuration, then you can run `kfctl generate all -V`.
 
 After your ingress DNS is ready, you need to create a `CNAME` in your DNS records.
 

diff --git a/content/docs/aws/deploy/existing-cluster.md b/content/docs/aws/deploy/existing-cluster.md
@@ -9,16 +9,26 @@ This is one step of [installing Kubeflow](/docs/aws/deploy/install-kubeflow), pl
 
 ### Deploy Kubeflow on existing Amazon EKS Cluster
 
-If you would like to deploy Kubeflow on existing Amazon EKS cluster, the only difference in setup is when you initialize the platform setup. Since you manage your own cluster resources, you need to provide `AWS_CLUSTER_NAME` and `AWS_NODEGROUP_ROLE_NAMES`.
+If you would like to deploy Kubeflow on existing Amazon EKS cluster, the only difference in setup is when you initialize the platform setup. Since you manage your own cluster resources, you need to provide `AWS_CLUSTER_NAME`, `cluster region` and `worker roles`.
 
+1. Download `kfctl` binary and config file
+
+    ```shell
+    # Add kfctl to PATH, to make the kfctl binary easier to use.
+    tar -xvf kfctl_<release tag>_<platform>.tar.gz
+    export PATH=$PATH:"<path to kfctl>"
+
+    # Download config files
+    export CONFIG="/tmp/kfctl_aws.yaml"
+    wget https://raw.githubusercontent.com/kubeflow/kubeflow/master/bootstrap/config/kfctl_aws.yaml -O ${CONFIG}
+    ```
 
-1. Retrieve the Amazon EKS cluster name, AWS Region, and IAM role name for your worker nodes. Set these values to the following environment variables.
+
+1. Retrieve the Amazon EKS cluster name, AWS Region, and IAM role name for your worker nodes. Set these values in the manifest file.
 
     ```shell
-    export KFAPP=kfapp
-    export REGION=<YOUR EKS CLUSTER REGION>
     export AWS_CLUSTER_NAME=<YOUR EKS CLUSTER NAME>
-    export AWS_NODEGROUP_ROLE_NAMES=<YOUR NODE GROUP ROLE NAMES>
+    export KFAPP=${AWS_CLUSTER_NAME}
     ```
 
     > Note: To get your Amazon EKS worker node IAM role name, you can check IAM setting by running the following commands. This command assumes that you used `eksctl` to create your cluster. If you use other provisioning tools to create your worker node groups, please find the role that is associated with your worker nodes in the Amazon EC2 console.
@@ -33,15 +43,21 @@ If you would like to deploy Kubeflow on existing Amazon EKS cluster, the only di
     eksctl-kubeflow-example-nodegroup-ng-185-NodeInstanceRole-1DDJJXQBG9EM6
     ```
 
-    If you have multiple node groups, you will see corresponding number of node group roles. In that case, please provide the role names as a comma-separated list.
+    Change cluster region and worker roles names in your `kfctl_aws.yaml`
+    ```yaml
+      region: us-west-2
+      roles:
+        - eksctl-kubeflow-example-nodegroup-ng-185-NodeInstanceRole-1DDJJXQBG9EM6
+    ```
+    > If you have multiple node groups, you will see corresponding number of node group roles. In that case, please provide the role names as an array.
 
-1. Initial setup
+1. Install Kubeflow
 
     ```shell
-    cd ${KUBEFLOW_SRC}
-
-    ${KUBEFLOW_SRC}/scripts/kfctl.sh init ${KFAPP} --platform aws \
-    --awsClusterName ${AWS_CLUSTER_NAME} \
-    --awsRegion ${REGION} \
-    --awsNodegroupRoleNames ${AWS_NODEGROUP_ROLE_NAMES}
+    kfctl init ${KFAPP} --config=${CONFIG} -V
+    cd ${KFAPP}
+    kfctl generate all -v
+    kfctl apply all -v
     ```
+
+All rest steps are exact same for both install kubeflow on new cluster and existing cluster. Please come back to [Installing Kubeflow](/docs/aws/deploy/install-kubeflow) to finish post installation step.
diff --git a/content/docs/aws/deploy/install-kubeflow.md b/content/docs/aws/deploy/install-kubeflow.md
@@ -4,12 +4,9 @@ description = "Instructions for deploying Kubeflow with the shell"
 weight = 4
 +++
 
-This guide describes how to use the `kfctl.sh` script to
+This guide describes how to use the `kfctl` golang cli to
 deploy Kubeflow on Amazon Web Services (AWS).
 
-> Note: Amazon Web Services (AWS) is moving from `kfctl.sh` to a command line interface (CLI) which gives you more control over your configuration and better reliability. It's under development and will be released around end of June.
-
-
 ## Prerequisites
 
 * Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl)
@@ -19,136 +16,127 @@ deploy Kubeflow on Amazon Web Services (AWS).
     * Enter your Access Keys ([Access Key ID and Secret Access Key](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)).
     * Enter your preferred AWS Region and default output options.
 * Install [eksctl](https://github.com/weaveworks/eksctl) (version 0.1.31 or newer) and the [aws-iam-authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html).
-* Install [jq](https://stedolan.github.io/jq/download/).
 
 You do not need to have an existing Amazon Elastic Container Service for Kubernetes (Amazon EKS) cluster. The deployment process will create a cluster for you.
 
 The installation tool uses the `eksctl` command and doesn't support the `--profile` option in that command.
 If you need to switch role, use the `aws sts assume-role` commands. See the AWS guide to [using temporary security credentials to request access to AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html).
 
 
-## Understanding the deployment process
-
-The deployment process is controlled by 4 different commands:
+## Kubeflow installation
 
-* **init** - The initial one-time set up.
-* **generate** - Creates the configuration files that define your various resources.
-* **apply** - Creates or updates the resources.
-* **delete** - Deletes the resources.
+1. Download the latest `kfctl` golang binary from [Kubeflow release page](https://github.com/kubeflow/kubeflow/releases) and unpack it.
 
-With the exception of `init`, all commands take an argument which describes the set of resources to apply the command to; this argument can be one of the following:
+    ```
+    # Add kfctl to PATH, to make the kfctl binary easier to use.
+    tar -xvf kfctl_<release tag>_<platform>.tar.gz
+    export PATH=$PATH:"<path to kfctl>"
+    ```
 
-* **platform** - All AWS resources; that is, anything that doesn’t run on Kubernetes. Like IAM policy attachments, Amazon EKS cluster creation, etc.
-* **k8s** - All Kubernetes resources. Such as Kubeflow packages and add-on packages like `fluentd` or `istio`.
-* **all** - Both AWS and Kubernetes resources.
+1. Download manifest and config setups
 
-### App layout
+    ```shell
+    # Download config files
+    export CONFIG="/tmp/kfctl_aws.yaml"
+    wget https://raw.githubusercontent.com/kubeflow/kubeflow/master/bootstrap/config/kfctl_aws.yaml -O ${CONFIG}
+    ```
 
-Your Kubeflow `app` directory contains the following files and directories:
+    * `kfctl_aws.yaml` is one of setup manifests, please check [kfctl_aws_cognito.yaml](https://github.com/kubeflow/kubeflow/blob/master/bootstrap/config/kfctl_aws_cognito.yaml) for the template to enable authentication.
 
-* **app.yaml** - Defines the configuration related to your Kubeflow deployment.
-    * These values are set when you run `kfctl init`.
-    * These values are snapshotted inside `app.yaml` to make your app self contained.
-* **${KFAPP}/aws_config** - A directory that contains a sample `eksctl` cluster configuration file that defines the AWS cluster and policy files to attach to your node group roles.
-    * This directory is created when you run `kfctl.sh generate platform`.
-    * You can modify the `cluster_config.yaml` and `cluster_features.sh` files to customize your AWS infrastructure.
-* **${KFAPP}/k8s_specs** - A directory that contains YAML specifications for daemons deployed on your Kubernetes Engine cluster.
-* **kustomize** is a directory that contains the kustomize packages for Kubeflow applications.
-    * The directory is created when you run `kfctl generate`.
-    * You can customize the Kubernetes resources (modify the manifests and run `kfctl apply` again).
+    - If you plan to use `kfctl` to create a new eks cluster, please remove follow lines in the manifest file.
+    - If you want to install on existing EKS cluster, please change roles to your worker node group roles. See [existing cluster](/docs/aws/deploy/existing-cluster) for details.
 
-The provisioning scripts can either bring up a new cluster and install Kubeflow on it, or you can install Kubeflow on your existing cluster. We recommend that you create a new cluster for better isolation.
+    ```shell
+    roles:
+      - eksctl-kubeflow-aws-nodegroup-ng-a2-NodeInstanceRole-xxxxxxx
+    ```
 
-If you experience any issues running these scripts, see the [troubleshooting guidance](/docs/aws/troubleshooting-aws) for more information.
+1. Run the following commands to set up your environment and initialize the cluster.
 
+    Since there're many ways to create your cluster, we highly recommend you to get our own eks cluster ready.
 
-## Kubeflow installation
+    Note: If you would like to install Kubeflow on your existing EKS cluster,
+    please skip this step and follow the setup instructions for an [existing cluster](/docs/aws/deploy/existing-cluster) instead.
 
-1. Run the following commands to download the latest `kfctl.sh`
+    ```
+    export KFAPP=kfaws
 
-    ```shell
-    export KUBEFLOW_SRC=/tmp/kubeflow-aws
-    export KUBEFLOW_TAG=v0.5-branch
+    kfctl init ${KFAPP} --config=${CONFIG} -V
+    cd ${KFAPP}
 
-    mkdir -p ${KUBEFLOW_SRC} && cd ${KUBEFLOW_SRC}
-    curl https://raw.githubusercontent.com/kubeflow/kubeflow/${KUBEFLOW_TAG}/scripts/download.sh | bash
+    kfctl generate all -V
+    kfctl apply all -V
     ```
 
-    * KUBEFLOW_SRC - Full path to your preferred download directory. Please use the full absolute path, for example `/tmp/kubeflow-aws`
+    * KFAPP - Use a relative directory name here rather than absolute path, such as `kfapp`. It will be used as eks cluster name.
+    * CONFIG - Path to the configuration file
 
-1. Run the following commands to set up your environment and initialize the cluster.
 
-    > Note: If you would like to install Kubeflow on your existing EKS cluster, please skip this step
-    > and follow the setup instructions for an [existing cluster](/docs/aws/deploy/existing-cluster) instead.
-    > When you are finished, return here and resume with the next step.
+    *Important!!!* By default, these scripts create an AWS Application Load Balancer for Kubeflow that is open to public. This is good for development testing and for short term use, but we do not recommend that you use this configuration for production workloads.
 
+    To secure your installation, Follow the [instructions](/docs/aws/authentication) to add authentication.
 
-    ```shell
-    export KFAPP=kfapp
-    export REGION=us-west-2
-    export AWS_CLUSTER_NAME=kubeflow-aws
 
-    ${KUBEFLOW_SRC}/scripts/kfctl.sh init ${KFAPP} --platform aws \
-    --awsClusterName ${AWS_CLUSTER_NAME} \
-    --awsRegion ${REGION}
+1. Wait for all the resources to become ready in the `kubeflow` namespace.
+    ```
+    kubectl -n kubeflow get all
     ```
 
+1. Get Kubeflow service endpoint and copy link in browser.
 
-    * AWS_CLUSTER_NAME - Specify a unique name for your Amazon EKS cluster.
-    * KFAPP - Use a relative directory name here rather than absolute path, such as `kfapp`.
-    * REGION - Use the AWS Region you want to create your cluster in.
-
-1. Generate and apply platform changes.
-
-    You can customize your cluster configuration, control plane logging, and private cluster endpoint access before you `apply platform`, please see [Customizing Kubeflow on AWS](/docs/aws/customizing-aws) for more information.
+    ```
+    kubectl get ingress -n istio-system
 
-    ```shell
-    cd ${KFAPP}
-    ${KUBEFLOW_SRC}/scripts/kfctl.sh generate platform
-    # Customize your Amazon EKS cluster configuration before following the next step
-    ${KUBEFLOW_SRC}/scripts/kfctl.sh apply platform
+    NAMESPACE      NAME            HOSTS   ADDRESS                                                             PORTS   AGE
+    istio-system   istio-ingress   *       a743484b-istiosystem-istio-2af2-xxxxxx.us-west-2.elb.amazonaws.com   80      1h
     ```
 
-    > Note: If you see `no kind "ClusterConfig" is registered for version "eksctl.io/v1alpha5"` error, it means your eksctl version is low and not compatible with latest version. Please upgrade it and have another try.
+    This deployment may take 3-5 minutes to become ready. Verify that the address works by opening it in your preferred Internet browser. You can also run `kubectl delete istio-ingress -n istio-system` to remove the load balancer entirely.
 
-1. Generate and apply the Kubernetes changes.
+## Post Installation
 
-    ```shell
-    ${KUBEFLOW_SRC}/scripts/kfctl.sh generate k8s
-    ```
+Kubeflow 0.6 release brings multi-tenancy support and user are not able to create notebooks in `kubeflow`, `default` namespace. Instead, please create a `Profile` using `kubectl apply -f profile.yaml` and profile controller will create new namespace and service account which is allowed to create notebook in that namespace.
 
-    __*Important!!!*__ By default, these scripts create an AWS Application Load Balancer for Kubeflow that is open to public. This is good for development testing and for short term use, but we do not recommend that you use this configuration for production workloads.
+```yaml
+apiVersion: kubeflow.org/v1alpha1
+kind: Profile
+metadata:
+  name: aws-sample-user
+spec:
+  owner:
+    kind: User
+    name: aws-sample-user
+```
 
-    To secure your installation, you have two options:
-
-    * Disable ingress before you `apply k8s`. Open `${KUBEFLOW_SRC}/${KFAPP}/env.sh` and edit the `KUBEFLOW_COMPONENTS` environment variable. Delete `,\"alb-ingress-controller\",\"istio-ingress\"` and save the file.
+## Understanding the deployment process
 
-    * Follow the [instructions](/docs/aws/authentication) to add authentication before you `apply k8s`
+The deployment process is controlled by 4 different commands:
 
-    Once your customization is done, you can run this command to deploy Kubeflow.
-    ```shell
-    ${KUBEFLOW_SRC}/scripts/kfctl.sh apply k8s
-    ```
+* **init** - The initial one-time set up.
+* **generate** - Creates the configuration files that define your various resources.
+* **apply** - Creates or updates the resources.
+* **delete** - Deletes the resources.
 
-1. Wait for all the resources to become ready in the `kubeflow` namespace.
-    ```
-    kubectl -n kubeflow get all
-    ```
+With the exception of `init`, all commands take an argument which describes the set of resources to apply the command to; this argument can be one of the following:
 
-1. Open Kubeflow Dashboard
-    * If you chose to use a load balancer, you can retrieve the public DNS name here.
+* **platform** - All AWS resources; that is, anything that doesn’t run on Kubernetes. Like IAM policy attachments, Amazon EKS cluster creation, etc.
+* **k8s** - All Kubernetes resources. Such as Kubeflow packages and add-on packages like `fluentd` or `istio`.
+* **all** - Both AWS and Kubernetes resources.
 
-        ```shell
-        kubectl get ingress -n istio-system
+### App layout
 
-        NAMESPACE      NAME            HOSTS   ADDRESS                                                             PORTS   AGE
-        istio-system   istio-ingress   *       a743484b-istiosystem-istio-2af2-xxxxxx.us-west-2.elb.amazonaws.com   80      1h
-        ```
+Your Kubeflow `app` directory contains the following files and directories:
 
-        This deployment may take 3-5 minutes to become ready. Verify that the address works by opening it in your preferred Internet browser. You can also run `kubectl delete istio-ingress -n istio-system` to remove the load balancer entirely.
+* **app.yaml** - Defines the configuration related to your Kubeflow deployment.
+    * These values are set when you run `kfctl init`.
+    * These values are snapshotted inside `app.yaml` to make your app self contained.
+* **${KFAPP}/aws_config** - A directory that contains a sample `eksctl` cluster configuration file that defines the AWS cluster and policy files to attach to your node group roles.
+    * This directory is created when you run `kfctl generate platform -V`.
+    * You can modify the `cluster_config.yaml` and `cluster_features.yaml` files to customize your AWS infrastructure.
+* **kustomize** is a directory that contains the kustomize packages for Kubeflow applications.
+    * The directory is created when you run `kfctl generate`.
+    * You can customize the Kubernetes resources (modify the manifests and run `kfctl apply` again).
 
-    * If you didn't create a load balancer, please use port-forwarding to visit your cluster. Run following command and visit `localhost:8080`.
+The provisioning scripts can either bring up a new cluster and install Kubeflow on it, or you can install Kubeflow on your existing cluster. We recommend that you create a new cluster for better isolation.
 
-        ```shell
-        kubectl port-forward -n kubeflow `kubectl get pods -n kubeflow --selector=service=ambassador -o jsonpath='{.items[0].metadata.name}'` 8080:80
-        ```
+If you experience any issues running these scripts, see the [troubleshooting guidance](/docs/aws/troubleshooting-aws) for more information.