pivotal / docs-tap Goto Github PK

Throughout the doc, need to call out to replace "TANZU-NET-USER" and "TANZU-NET-PASSWORD" in the yaml files with user credentials.

Suggest also to change name depending on final destination of where the packages will land eg if "registry.vmware.com" then "Tanzu Net" is not intuitive.

TKGm installation is handled in the in the page Installing Part I: Prerequisites, EULA, and CLI, while we have a separate section for Installing on a Tanzu Community Edition v0.9.1 Cluster. We need to maintain consistency with the way we document.

In https://github.com/pivotal/docs-tap/blob/main/install.md#-install-api-portal, what is the need for creating the secret? if this is to pull the imgpkg bundle from tanzunet, it is already taken care by creating imagepullsecret in the earlier sections.
if this is created for some other reason, please specify where this secret will be used in later stages to provide some clarity to the user.

Add detailed prerequisites. Collate validated prerequisites from each Eng team. An example would be...

• Tanzu Net account
• Internet access from host and k8s cluster (call out dark site install not supported yet or similar)
• List of URLs that need to be reached from cluster and also from workstation eg network.pivotal.io, registry.pivotal.io, github, dockerhub etc
• Flux (for App Acc)
• An image registry (for TBS and for petclinic images for tutorial) with a min of 7GB free
• a git repo (plus creds/token)
• git client
• carvel tools

breakdown the huge code block into separate detailed steps and where each command can be copied easily using the doc copy button

add step to navigate to folder where app resides

reduce number of steps by opening file using full path

clearly show what was changed in the vetlist.html file

clearly highlight that image in kapp-deploy-spring-petclinic.yaml needs to be updated with new image

eg in "Install Cloud Native Runtimes", the example output provided differed from actual output when command was run. Its missing "pdb" and "local_dns" entries

Throughout the tutorial there are no indications that all steps are working as planned until the very end where you have to verify you can access the app. Suggest to add troubleshooting tips or link to appendix with them.

See: https://vmware.slack.com/archives/C01G0P79LSE/p1635362254035800?thread_ts=1635333832.024200&cid=C01G0P79LSE

In the interest of conceptual clarity I think it might be better to have the instructions use different name for the instantiated template. I.e. personally I am/was having a lot of confusion between the things / concepts that are more like 'instances' versus the things that are more like 'types / classes / templates'. Naming the instance of the template the same as the template itself 'tanzu-java-web-app' doesn't help there at all. So instead of 'tanzu-java-web-app' maybe it could be called 'my-first-tanzu-app' or something like that. Thereby it would be clear that

a) you could pick a different name if you wanted to
b) you could instantiate the template multiple times
c) each time you do that you are in fact creating a new and distinct app/component.

@mpriamo
install.md at step 3 shows a sample values yaml where to install full profile, profile:full needs to be provided.
it would be good to mention what value to provide to install other profiles Developer Light. Shared Tools and Operator Light

Please change section name and link everywhere. as there is no section called install-packages.
Follow the instructions in Install Packages above.

At end of tutorial add a note that the app wont show in App Live View if it has scaled to zero. Therefore access the app and it will then show in App Live View again.

TAP and TKG are not a legally recognized names for VMware Tanzu Application Catalog and VMware Tanzu Kubernetes Grid. Please remove "TAP"and "TKG" from docs unless this is an allowed exception.

add link on how to install kubectl eg https://kubernetes.io/docs/tasks/tools/ rather than user having to google/search it themselves

Eg for "Add the TAP package repository" and "Install Cloud Native Runtimes" there is no overview/intro/summary of steps that will be performed. Fix these and throughout.

images/tap-conceptual-value.jpg

This image has Harvey Balls that indicate the status of progress on individual features. They should be removed from the graphic.
https://en.wikipedia.org/wiki/Harvey_balls

eg "In TKG environments, Contour addons that are already be present might conflict with the Cloud Native Runtimes installation"

"addons" in TKG are known as "packages"

Also, fix grammar in this sentence.

install learning center step-3 Install Learning Center operator, include namespace -n tap-install. Since earlier instructions to add the repo in tap-install ns, package will be available only on that namespace. Hence, this current instruction to install learning center on default ns won't work

tanzu package install default-supply-chain
--package-name default-supply-chain.tanzu.vmware.com

Package name should be default-supply-chain-testing.tanzu.vmware.com.

My team recently added Source Controller component documentation to docs-tap.
I see them in beta4 staging, but not in the beta3 docs.
They should be displayed in beta3+.

Can you please make the updates as required?

Here are the two pages in question (and they should also show up in the beta3+ TOC):
https://docs-staging.vmware.com/en/VMware-Tanzu-Application-Platform/0.4/tap-0-4/GUID-source-controller-about.html
https://docs-staging.vmware.com/en/VMware-Tanzu-Application-Platform/0.4/tap-0-4/GUID-source-controller-troubleshooting.html

Step 3 of Add the Tanzu Application Platform Package Repository on this page explains that "TAP-REPO-IMGPKG is the Tanzu Application Platform repo bundle artifact reference". While it continues to give an example (registry.tanzu.vmware.com/tanzu-application-platform/tap-packages:0.2.0), that specific url is not currently correct, and most users won't know how to find the working one by finding the tap-package-repo-bundle download on TanzuNet.

To Verify installed kapp-controller version:
To Verify installed secretgen-controller version:

In the doc it calls out "Tanzu Kubernetes Grid", please add link to its doc page.

Add steps on how to access Application Accelerator eg run "kubectl get -n accelerator-system service" and use external ip returned for the acc-ui-server

re step 1 "Use the "Spring PetClinic sample Accelerator to generate a new project called spring-petclinic-eks and download the zip file".... suggest to rename "spring-petclinic-eks" so we are not a free advertising agency for our competition! Update screengrab and steps throughout

re step 3, add more details here and separate out the steps from the code block eg show contents of "tap-sa.yaml" and then the individual kubectl commands

re step 3, call out that user has to update the yaml to include their own registry. The example is very confusing as its an internal private registry in VMware folk wont have access to.

re step 3, call out to enter registry credentials

re step 4, like above, breakdown the huge code block into individual blocks of yaml and commands etc

re step 4, call out to replace registry with users registry

re step 4, call out to replace git url with users git repo

re step 5, like above, breakdown the huge code block into individual blocks of yaml and commands etc and also fix indentation.

re step 5, call out to replace registry with users registry

Eg "Install Cloud Native Runtimes" add step 5 on how to verify install (tanzu package installed list -n tap-install) or add note that will be verified later. As a reader I started an install and am now moving on to install something else without known the previous install was successful!

There is one discrete paragraph in "Packages in Tanzu Application Platform v0.1" that calls out to install TBS. Give it its own section / sub-heading.

Eg in the "Install Packages" section there are steps that are of low value and are not needed, they are informational, and actually are not how to install packages in this section!

In the "Install Cloud Native Runtimes" section, there first two steps are are of low value as the schema is provided in step 3

Like ticket x, remove steps 1 & 2. If its decided to keep the steps, then add the commands here rather than jumping back and forth to work it out.

For step 5, potentially add the details/steps here so less linking out. Also, I had to read the linked section until found steps (step 9) on sample accelerators. Not a great UX.

My team has completed an initial draft of the Spring Boot Conventions component docs.
English is not the primary language of person who drafted them.
Could someone from docs please review the following pages and make any corrections in syntax/grammer/tense, etc... so the information can be more readily consumed?

The pages in question can be found in this directly and below:
/docs-tap/spring-boot-conventions/

If you have any questions please feel free to reach out to me directly on slack!

Please combine sections About Installing Packages and General Procedure to Install a Package as both are talking about gathering values schema.

I found broken links in (https://docs.vmware.com/en/VMware-Tanzu-Application-Platform/0.3/tap-0-3/GUID-install-components.html): Wherever it mentions:

Where PACKAGE-NAME is the name of the package listed in step 5 of Add the Tanzu Application Platform Package Repository above.

It was referencing an anchor on the same page, and that anchor doesn't exist.

The correct page should be on this page and in Step 3.

List out the actual delete commands rather than user having to work them out

In install-general, the package name tanzu-cli-bundle-*-amd64.tar is incorrect for current versions. The current name is tanzu-framework-*-amd64.tar (for all three platforms)

Link for Services Toolkit is broken.

Should this be for v3?

These steps need to be more generic. Eg ensure your context is set to desired cluster to be used for TAP install

re "Set the context to the context by running: aks-tap-cluster" rephrase as it reads that the user should set context to this exact context which the reader wont have! Those working with k8s will know this but you cant make that assumption that every reader has a k8s background!

If using examples, try use TKG in the examples, or generic names. Otherwise we are an advertising agency for our competitors!

Little value to step 4 "List the parameters that are in use by running", suggest to remove

eg the downloaded yaml is called "sample-packagerepo.yaml" yet if to create your own the doc says to use "tap-package-repo.yaml". This adds to confusion and also meaning the copy/paste commands cant be used

Please remove kapp-controller, secretgen-controller and cert manager 1.5.3, flux2 source-controller, from Prerequisites of Install Supply Chain Choreographer as it is already covered in TAP prerequisites section.

Document when installing Application Live View the list of connector_namespaces namespaces specified in values.yaml need to already exist or installation fails.

Improve wording as I'm unsure am I to perform this step now or later. Unknown if it has dependencies on others steps to be performed first.

Improve wording as TAP beta is not for production environments.

Add some notes to inform reader that installing TBS can take 20 to 40mins or longer. It's heavily dependent on the readers network connection from both pulling from Tanzu Net and also pushing to their registry. There is approx 7 GB of images downloaded and then uploaded. <- duration and size to be verified by PM/Eng

After installing prereqs per Part I, the first use of the Tanzu CLI in Part II depends on a plug-in for imagepullsecret that was downloaded but not installed.

The missing command is

tanzu plugin install --local ./cli imagepullsecret

After going through Part I, I found myself wondering "what's next". Maybe add a "Now you're ready to proceed to Part II" with a link at the bottom of that page?

The following workaround for TAP to work with TSM is missing in TAP Beta 3 documentation,
https://github.com/pivotal/docs-tap/blob/main/install-tsm.md

Add "Download PDF" button to beta 1 docs

Unable to add tanzu-tap-registry. Failed with Signal Killed.

$ tanzu package repository add tanzu-tap-repository --url registry.tanzu.vmware.com/tanzu-application-platform/tap-packages:0.2.0 --namespace tap-install

Error: signal: killed

✖  signal: killed

Review and revise minimum cluster configuration for beta 2. Also add note to the effect of that to increase resources to accommodate additional workload and agents and extensions eg Tanzu Mission Control

re "Cloud Native Runtimes, Application Accelerator, and Application Live View are available as a
package in the TAP repo bundle"... suggest to rephrase this, as a reader I thought, OK, so where is this "TAP repo bundle"? Not immediately clear that adding the package repo is how its downloaded. Its only after reading that section later in the doc it becomes clear

re "For instructions on how to add the TAP package repository and install packages from the repository, see Add PackageRepositories and Install Packages below."... need to improve UX here. As a reader I'm confused if I should do this step now or later

it says Before you install the packages, ensure that you have completed the prerequisites, configured and verified the cluster, accepted the EULA, and installed the Tanzu CLI and the package plugin

For TAP many plugins are required so either say Tanzu CLI and tanzu CLI plugins or name plugins package, imgpullsecret, accelerator, and apps plugins

Followed steps for Install default supply chain :

1. Created imagepullsecret registry-credentials.
2. Installed default supply chain.
3. Installed all other TAP packages.
4. As per the Note: The service-account service account and needed secrets are created at the end of this guide, in Set Up Developer Namespaces to Use Installed Packages.
5. Created dev-namespace.yml containing mentioned resources in Set Up Developer Namespaces to Use Installed Packages.
6. kubectl apply -f dev-namespace.yml fails with Error from server (AlreadyExists): error when creating "dev-namespace.yml": secrets "registry-credentials" already exists
   which is expected as same secret is getting created in step 1.
   Please modify instructions to create secret only once.

Several times throughout the doc the user has to create yaml files and copy and paste the contents in from the doc. This is wide open to error and slows down the install process. All required yamls should be provided in package/repo or similar.

Need to remove all references to Pivotal from docs

Check with component teams where the bits are landing eg is it registry.vmware.com or registry.tanzu.vmware.com or ?

For beta 1 docs, replace

"For Tanzu Kubernetes Grid, ensure that you are using Tanzu Kubernetes Grid v1.14.0 or later. Clusters of this version have kapp-controller v0.20.0 pre-installed."

with

"For Tanzu Kubernetes Grid, ensure that you are using Tanzu Kubernetes Grid v1.4.0 or later. Clusters of this version have kapp-controller v0.23.0 pre-installed."