Deployment documentation is broken

[tejarora]

What is the URL of the document?
Issues pertain to 3 documents (3 different branches)

1. https://github.com/awslabs/kubeflow-manifests/tree/main/docs/deployment/vanilla
2. https://github.com/awslabs/kubeflow-manifests/tree/release-v1.3.1-aws-b1.0.0/distributions/aws/examples/vanilla
3. https://github.com/awslabs/kubeflow-manifests/tree/v1.3-branch/distributions/aws/examples/vanilla

Which section(s) is the issue in?
See below

What needs fixing and describe the solution you'd like?
(a)
All 3 URLs above have a vague and incomplete step
"AWS IAM permissions to create roles and attach policies to roles."

(b)
The v1.3 branches have no configuration for kubeflow version, but the main branch does. In fact the main branch talks about cloning the kubeflow repo, but the branch documents do not.
How does one one set kubeflow version using v1.3* branches? Which branch is prescribed for deployment?
This is a mess

(c) The document for the branch release-v1.3.1-aws-b* has a step that is asking to use a different branch v1.3-branch

(d) The documents for the v1.3 branches have their deployment step as:
while ! kustomize build example
Is this deployment not for serious use? Is it just for experimentation and not ready for production??

(e) The v1.3 documents talk about changing a password, but there is no file whatsoever on the branches that contains the password. There is reference to a dex/base/config-map.yaml but this file does not exist in the branches. It actually exists in the kubeflow repo, which the branch documentation does not talk about at all....

Additional context
I would like to use kubeflow on a production EKS cluster, but the only documentation I found to help with that is well short of expectations.

[goswamig]

@tejarora thanks for reporting this.

a) This is just a general pre-requisite that user/role which are trying to deploy the kubeflow has permission to create role and attach polices. This is the IAM user/role who is deploying the kubeflow, which could be "you (mac)" if "you(mac)" are trying to deploy kubeflow on your eks cluster or it could be "your(Ec2)" instance from where you are deploying kubeflow.

b/c) the git clone instruction has checkout branch

 git checkout v1.3-branch 

d) This step has been borrowed from official guide, however its basically retry the deployment if it fails. You can always opt for multiple steps deployment.

e) You're right, this repo does not contain that file, because this repo is manifest hosting repo. Manifests pulls different files/containers as it does the deployment. Agree that the instruction here is a bit misleading.

We will work on improving the documentation.

[Harikantipudi]

@goswamig

Also the V1.4-branch-stale , does that mean all the future releases will now be from main and the check out to respective branch

From the below , what will AWS_MANIFESTS_BUILD value for 1.4/1.5 be considering , I now see only below branches , not sure if i am missing something here please ??

v1.3-branch, v1.3.1-aws-b1.0.0, [v1.4-branch-stale

Clone the awslabs/kubeflow-manifest repo, kubeflow/manifests repo and checkout the desired branches Substitute the value for KUBEFLOW_RELEASE_VERSION(e.g. v1.4.1) and AWS_MANIFESTS_BUILD(e.g. v1.4.1-b1.0.0) with the branch or tag you want to use

export KUBEFLOW_RELEASE_VERSION=<>
export AWS_MANIFESTS_BUILD=<>
git clone https://github.com/awslabs/kubeflow-manifests.git
cd kubeflow-manifests
git checkout ${AWS_MANIFESTS_BUILD}
git clone --branch ${KUBEFLOW_RELEASE_VERSION} https://github.com/kubeflow/manifests.git upstream

[ryansteakley]

@Harikantipudi Hello, the AWS_MANIFESTS_BUILD values for 1.4/1.5 are not out as we have not released official support for those versions. As your question about V1.4-branch-stale all work for v1.4 is now occuring in the main branch. We are planning on releasing v1.4 support soon, you can track our progress here #27

[surajkota]

Hi @tejarora, @Harikantipudi

initial question and (b): little bit of background here:

• I have added some background in releases and versioning documentation to v1.3-branch which should answer your questions on this and also help understand why the branches are different. Added to main branch as well
• General industry standard, branches are used for development and once the code and artifacts are stable for a release a tag is cut. That is what you see under releases: https://github.com/awslabs/kubeflow-manifests/releases. For production deployment, we recommend you to use a tag so you can reproduce your deployment.

(a) Removed this instruction since it is not adding value(#141, #142). Various AWS resources like eks cluster, iam roles, rds, s3 are created depending on deployment option and each service already has their own documentation on the required policies

(c) Thanks for pointing the issue. Instructions do advice to checkout a release tag but the code is out of sync. This was a miss from our side but since the tag is cut, we wont we able to modify it(we are in process of migrating docs from kubeflow website). I have updated the branch for now which should help with future releases.

(e) addressed in #142 and #146 and created a PR for upstream where there error originally came from kubeflow/manifests#2179

Closing this issue. Please reopen or create a new one in case you still face issues

[surajkota]

I have also added a badge on the top of main readme in the main branch which would reflect which Kubeflow version is being developed - https://github.com/awslabs/kubeflow-manifests/blob/main/README.md

[surajkota]

All the feedback has been addressed and documentation is now available on the new website which should streamline the experience: https://awslabs.github.io/kubeflow-manifests/