pivotal-cf / docs-build-service

Documentation to help with installing and using Build Service

Tanzu Build Service Documentation

This repository contains content for Tanzu Build Service documentation. We publish the Tanzu Build Service documentation at https://docs.pivotal.io/build-service/index.html.

How To Contribute

Please help us improve the accuracy and completeness of the Tanzu Build Service documentation by contributing content, editing, or expertise.

A common way to contribute is to file a pull request through GitHub.

Every topic in the Tanzu Build Service documentation has a corresponding file in the https://github.com/pivotal-cf/docs-build-service content repository in GitHub. To locate the source file for a topic, navigate to the topic on the documentation site and click "View the source for this page in GitHub" at the bottom of the topic.

Versions and Branching

Branch Name	Content	Location
master	DO NOT USE
v1.14	Tanzu Build Service 1.14	https://docs-staging.vmware.com/en/draft/Tanzu-Build-Service/1.14/vmware-tanzu-build-service/index.html
v1.13	Tanzu Build Service 1.13	https://docs.vmware.com/en/Tanzu-Build-Service/1.13/vmware-tanzu-build-service/index.html
v1.12	Tanzu Build Service 1.12	https://docs.vmware.com/en/Tanzu-Build-Service/1.12/vmware-tanzu-build-service/index.html
v1.11	Tanzu Build Service 1.11	https://docs.vmware.com/en/Tanzu-Build-Service/1.11/vmware-tanzu-build-service/index.html
v1.10	Tanzu Build Service 1.10	https://docs.vmware.com/en/Tanzu-Build-Service/1.10/vmware-tanzu-build-service/index.html
v1.9	Tanzu Build Service 1.9	https://docs.vmware.com/en/Tanzu-Build-Service/1.9/vmware-tanzu-build-service/index.html
v1.7	Tanzu Build Service 1.7	https://docs.vmware.com/en/Tanzu-Build-Service/1.7/vmware-tanzu-build-service/GUID-index.html
v1.6	Tanzu Build Service 1.6	https://docs.vmware.com/en/Tanzu-Build-Service/1.6/vmware-tanzu-build-service/GUID-index.html
v1.5	Tanzu Build Service 1.5	https://docs.vmware.com/en/Tanzu-Build-Service/1.5/vmware-tanzu-build-service/GUID-index.html

Continuous Integration and Continuous Delivery

We use Concourse pipelines to provide continuous integration and continuous delivery. Any change made to this repository or the https://github.com/pivotal-cf/docs-build-service content repository triggers a "bind" where the disparate parts of the documentation are assembled into a single web app. A successful bind triggers pushing the app to the staging site, https://docs-pcf-staging.cfapps.io/build-service/. After review, the staging site is manually pushed to the production site, https://docs.pivotal.io/platform/build-service/.

Concourse Pipeline:

https://concourse.run.pivotal.io/teams/cf-docs/pipelines/tanzu-build/?group=build-service

docs-build-service's Issues

Provide examples for Harbor each time a registry workflow is referenced in the docs

Landing Page

Production Link: https://docs.pivotal.io/build-service/0-2-0/

Things to document:

Add link to kp CLI docs https://github.com/pivotal/build-service-cli/blob/master/docs/kp.md. This was requested by the field several times

Create a new page or linkable docs resource explaining how to pull cluster builders

Should help with synced-secrets

Update the docs' information heirarchy

Change the left column's heirarchy on this page to match the proposal on the right

Helm 3 and Pivotal Knowledge Base article

docs-build-service/installing.html.md.erb

Line 25 in 1a0114c

* Install an ingress controller on the Kubernetes cluster where you install Build Service. The Build Service expects an ingress controller and an ingress service to configure its own ingress. For more information, see [How to set up an Ingress Controller for a <%= vars.k8s_runtime_abbr %> cluster](https://community.pivotal.io/s/article/how-to-set-up-an-ingress-controller-for-a-pks-cluster) in the Pivotal Knowledge Base.

This article is for Helm 2; however, Helm 3 was released in November 2019 and it changed the CLI and the --name is no longer supported.

See the nginx docs: Installation with Helm

I used:

helm install nginx nginx-stable/nginx-ingress --set rbac.create=true --namespace ingress --set controller.config.proxy-buffer-size=16k

Using TBS -- Managing Builders

Production: https://docs.pivotal.io/build-service/0-1-0/managing-builders.html

hackmd: https://hackmd.io/ph7cDWeLRsqudafXI2Ul6w

It is unclear that relocation will require users to have the registry cert on the local machine

It is unclear that relocation will require users to have the registry cert on the local machine: https://vmware.slack.com/archives/C010436S7FA/p1596464856235100

Using TBS -- Managing the Store

Production: https://docs.pivotal.io/build-service/0-1-0/managing-store.html

hackmd: https://hackmd.io/c2K6PHN9S7uLyIydBH0URw

Document how to output kpack logs from a build pod into a third party tool

eg. Splunk or Fluentbit.

This was an explicit ask from the EU, but we've received this feedback before from PAs. Including Justin Seeley, who specified this would use case would important functionality for the AKS field to feel confident about selling TBS.

Updating Build Service Dependencies

Production: https://docs.pivotal.io/build-service/0-2-0/updating-deps.html

Docs issues that we should cover:

https://github.com/orgs/pivotal/projects/7#card-42479030 (more direct instructions on where to go to get new stack and buildpack versions)
Suggested upgrade use cases - kp import vs. kp store add or kp stack update
This page currently points to Paketo, should point back to TBS Deps and Kashyap's GA buildpack pages in Tanzunet (Java, Go, Node)

PAs don't understand that harbor either requires a project OR they don't understand that a project is not a repo name

PAs don't understand that harbor either requires a project OR they don't understand that a project is not a repo name

https://vmware.slack.com/archives/CU3LBH422/p1596130341115900

FAQs

Production: https://docs.pivotal.io/build-service/0-1-0/faq.html

hackmd: https://hackmd.io/9APs6H7ZR9-7svaPpE5e0g

FAQ

Production: https://docs.pivotal.io/build-service/0-2-0/faq.html

Using Tanzu Build Service

Production: https://docs.pivotal.io/build-service/0-2-0/using.html

Configuring GitBot is recommended

Pivotal provides the GitBot service to synchronize pull requests and/or issues made against public GitHub repos with Pivotal Tracker projects. This service does not track individual commits.

If you are a Pivotal employee, you can configure Gitbot to sync your GitHub repo to your Pivotal Tracker project with a pull request. An ask+cf@ ticket is the fastest way to get write access if you get a 404 to the config repo.

If you do not want have pull requests and/or issues copied from GitHub to Pivotal Tracker, you do not need to take any action.

If there are any questions, please reach out to [email protected].

Using Tanzu Build Service - Managing Secrets

Production: https://docs.pivotal.io/build-service/0-2-0/managing-secrets.html

Docs issues that we should cover:

https://github.com/orgs/pivotal/projects/7#card-42479468 (service bindings)
https://github.com/orgs/pivotal/projects/7#card-42277624 (incorrect -git flag)
https://github.com/orgs/pivotal/projects/7#card-42277616 (git-ssh workflow, don't we already document this?)
https://github.com/orgs/pivotal/projects/7#card-42342687 (known Harbor gotcha)

Installing Tanzu Build Service

Production: https://docs.pivotal.io/build-service/0-1-0/installing.html

hackmd: https://hackmd.io/QlyVs-nLSfe2bY3OsUr3TA

Addition to Managing Builders section - How to modify a kp import builder or create a new builder w/ a certain language family removed

Addition to Managing Builders section - How to modify a kp import builder or create a new builder w/ a certain language family removed

Addition to Managing Builders section - Modifying a metabuildpack

. EG. User doesn’t want yarn 1) Look at the order of the node js buildpackage in the store 2) Add the non-yarn order from the nodejs builpackage to a custom builder.

Using TBS -- Managing Images and Builds

Production: https://docs.pivotal.io/build-service/0-1-0/managing-images.html

hackmd: https://hackmd.io/kwgmaiofTRuTpugKEBc37w

Secrets in Tanzu Build Service

Production: https://docs.pivotal.io/build-service/0-2-0/secrets-in-tbs.html

Things we should document:

Setting up secret syncer and why the user might want to do this

Using TBS -- Managing Projects

Production: https://docs.pivotal.io/build-service/0-1-0/managing-projects.html

hackmd: https://hackmd.io/e6SDkCJNR3WF3xBorL_gzg

Add additional details to Managing Images and Builds

Production: https://docs.pivotal.io/build-service/0-2-0/managing-images.html

The page is ready for 1.0 but could contain additional info:

• Outputting kpack logs to 3rd party tool like Splunk
• how to approach debugging in TBS

Using TBS -- Landing Page

Production: https://docs.pivotal.io/build-service/0-1-0/using.html

hackmd: https://hackmd.io/u_2BgkheTY698p2sxQjbQQ

Addition to Managing Images section - Using an environment variable to specify a particular version of a dependency

. We already have some information on this, but additional context about how buildpack versions don't map to dep versions so an env var is the best solution to this would help.

Using Tanzu Build Service With Projects

Production: https://docs.pivotal.io/build-service/0-2-0/tbs-with-projects.html

Release Notes

Production: https://docs.pivotal.io/build-service/0-2-0/release-notes.html

Using TBS -- Managing Secrets

Production: https://docs.pivotal.io/build-service/0-1-0/managing-secrets.html

hackmd: https://hackmd.io/-7Y1i4nBTmy0J3K3xhxJlA

Installing Tanzu Build Service Page

Consider replacing uaac-cli examples with uaa-cli

In order to leverage the operational/distribution ease of the golang UAA-cli, consider swapping out doc referencing the cf-uaac with the golang uaa-cli. This promotes the golang uaa-cli and removes the need for ruby thanks to OS-native binaries.

Thanks for your time/considering it 👍

Using Tanzu Build Service - Accessing Tanzu Build Service

Production: https://docs.pivotal.io/build-service/0-2-0/accessing-tbs.html

Using Tanzu Build Service - Managing Builders

Production: https://docs.pivotal.io/build-service/0-2-0/managing-builders.html

Docs issues that we should cover:

Take into account new kpack naming schema for the builders

How to configure a builder such that images that reference that builder are only rebuilt on a stack update
https://github.com/orgs/pivotal/projects/7#card-42755725 (How to modify a meta buildpack)
https://github.com/orgs/pivotal/projects/7#card-42755679 (Removing a language family, eg. PHP from the kp import builders)

Simplify TLS certificate directions

docs-build-service/installing.html.md.erb

Line 94 in 1a0114c

1. Create or use an existing TLS certificate for the Build Service domain. For more information, see [Configuring SSL Certificates](https://bosh.io/docs/director-certs/) in the BOSH documentation.

We manually generated out own cert following the directions in Director SSL Certificate Configuration with OpenSSL and then added the cert to Bosh Director like shown in the Harbor docs. This seems more approachable than modifying the Director deployment manifest.

Using TBS -- Accessing Hosted TBS

Production: https://docs.pivotal.io/build-service/0-1-0/accessing-tbs.html

hackmd: https://hackmd.io/Eac9i4dERQ-CH1bV8TitjQ

Updating Build Service Dependencies

Production: https://docs.pivotal.io/build-service/0-1-0/updating-deps.html

hackmd: https://hackmd.io/VHyUa6ZjSZynsPXviRNAWw

Secrets in TBS

Production: https://docs.pivotal.io/build-service/0-1-0/secrets-in-tbs.html

hackmd: https://hackmd.io/mKav2vU4TpuQV97X-n8ZfQ

Recommend Changing KUBECONFIG process

In the documentation here:

PATH-TO-KUBECONFIG is the path to the kubeconfig configuration file on your local machine. This file is required to enable Build Service to interact with the target cluster.

I would highly encourage either showing directions for creating a service account and building a kubeconfig, or recommending a small script that does it (here is a basic example)

In lots of kubernetes distributions, for example PKS, the tokens that exist in those kubeconfig files will expire fairly quickly so they are not long lasting.

Additionally, that kubeconfig file might contain many clusters, and the current context might not be setup for the correct one.

Using Tanzu Build Service - Managing Images and Builds

Production: https://docs.pivotal.io/build-service/0-2-0/managing-images.html

Docs issues we should cover:

https://github.com/pivotal/build-service/issues/272 (Outputting kpack logs to 3rd party tool like Splunk)
https://github.com/orgs/pivotal/projects/7#card-42755825 (Env Var usage to specify a particular version of a dependency)

Using Tanzu Build Service - Managing Stores

Prod: https://docs.pivotal.io/build-service/0-2-0/managing-stores.html

Using TBS -- Using TBS w/o Projects

Production: https://docs.pivotal.io/build-service/0-1-0/tbs-without-projects.html

hackmd: https://hackmd.io/e6SDkCJNR3WF3xBorL_gzg

Document how to consume .cnb buildpackage files when they are available

Our current offline dependency update includes using kp import and kbld for packaging and unpackaging.

Once .cnb buildpackage files are available on Tanzu Net, we should use that offline workflow in our documentation:

kp store add defeault -b buildpackage.cnb

Bundling/configuring k8s resources like Ingress, PVCs, etc.

Wanted to comment on this pull request about installation without cluttering up a legit conversation

Apologies for interjecting, but I presume the reason the nginx-ingress chart isn't being suggested as an alternative to raw k8s manifests is because it requires helm, which otherwise wouldn't be a requirement since pb uses duffle for deployments?

The only reason I bring it up is because I imagine having people push plain k8s manifests described in this README.md might to lead to drift or confusion, especially with upcoming k8s API deprecations and whatnot and such.

It might be worth considering, at some point, how an Ingress Controller / Ingress (or any collection of k8s resources) could be optionally packaged/versioned/leveraged/etc. From my very limited understanding of duffle, I wonder if those resources could be packaged with the duffle bundle and be (optionally) leveraged by users if they didn't want to manage an Ingress / Ingress Controller / PVC / etc. separately?

Again, don't mean to be obnoxious with unsolicited opinions, just figured I'd share. Obviously zero expectation to respond to this comment, feel free to close this whenever, etc.

Landing Page

Production: https://docs.pivotal.io/build-service/0-1-0/index.html

Hack MD: https://hackmd.io/7NOwl5YaQ9y0nEwCJaPgrA

Using Tanzu Build Service - Accessing Tanzu Build Service

Production: https://docs.pivotal.io/build-service/0-2-0/accessing-tbs.html

Using Tanzu Build Service - Managing Stacks

Production: https://docs.pivotal.io/build-service/0-2-0/managing-stacks.html

https://github.com/orgs/pivotal/projects/7#card-42481179

Release Notes

Production: https://docs.pivotal.io/build-service/0-1-0/release-notes.html

Release Notes: https://hackmd.io/1bUhKOfmTCa1G1Z2ALfYDg

Configuring PKS as an OIDC Provider

Production: https://docs.pivotal.io/build-service/0-1-0/configure-oidc.html

No hackmd file

Using TBS -- Managing the Stack

Production: https://docs.pivotal.io/build-service/0-1-0/managing-stack.html

hackmd: https://hackmd.io/oG_RAyDGQC20xviTdGFsZw

Update managing stacks and managing builders pages with stacks usecases paketo page

Add link or content from "stack use cases" readme (https://github.com/paketo-buildpacks/stacks) to TBS docs on the managing stacks (https://docs.pivotal.io/build-service/0-2-0/managing-stacks.html) and managing builders pages (https://docs.pivotal.io/build-service/0-2-0/managing-builders.html)

CI/CD Docs

The 0.2.0 release includes kp with significant improvements to kp CI/CD and CI/CD integration is the most common point of confusion. It would be valuable to have CI/CD specific page.