Identify/fix outdated docs (#6827)

### Description of the change Even if we have changed several things during recent months, our docs didn't get updated at the same pace. This PR (still a WIP draft) is trying to go through the docs and add TODOs where required and/or to add easy fixes. ### Benefits We will know which doc pages need a revamp/update/etc (screenshots, wording, etc...) ### Possible drawbacks N/A ### Applicable issues N/A ### Additional information Once finished, an issue summarizing all the TODOs should be created --------- Signed-off-by: Antonio Gamez Diaz <agamez@vmware.com>
vmware-tanzu · Feb 9, 2024 · 1f4aa27 · 1f4aa27
1 parent 01dffed
commit 1f4aa27
Show file tree

Hide file tree

Showing 20 changed files with 235 additions and 70 deletions.
diff --git a/site/content/docs/latest/background/README.md b/site/content/docs/latest/background/README.md
@@ -1,14 +1,14 @@
 # Kubeapps Background
 
-Big-picture explanations of higher-level Kubeapps concepts. Most useful for building understanding of a particular topic.
+Big-picture explanations of higher-level Kubeapps concepts. Most useful for building an understanding of a particular topic.
 
 | Background                                         | Description                                                                                      |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | [Architecture](./architecture.md)                  | Dive into the overall Kubeapps architecture.                                                     |
 | [Kubeapps API documentation](./update-api-docs.md) | Information about Kubeapps API and how to contribute to keep Kubeapps API documentation updated. |
 | [Multicluster mode](./multicluster.md) | Details on the multicluster mode of Kubeapps. |
 
-Alternatively, our [Tutorials section](../tutorials/README.md) contain step-by-step tutorials to help outline what Kubeapps is capable of while helping you achieve specific aims, such as installing Kubeapps or using an OIDC provider.
+Alternatively, our [Tutorials section](../tutorials/README.md) contains step-by-step tutorials to help outline what Kubeapps is capable of while helping you achieve specific aims, such as installing Kubeapps or using an OIDC provider.
 
 If you have a specific goal, but are already familiar with Kubeapps, take a look at our [How-to guides](../howto/README.md). These have more in-depth detail and can be applied to a broader set of features.
 

diff --git a/site/content/docs/latest/background/architecture.md b/site/content/docs/latest/background/architecture.md
@@ -10,6 +10,8 @@ At the heart of Kubeapps is an in-cluster Kubernetes dashboard that provides you
 
 The dashboard is written in the JavaScript programming language and is developed using the React JavaScript library.
 
+Please refer to the [Kubeapps Dashboard Developer Guide](../reference/developer/dashboard.md) for the developer setup.
+
 ### Kubeapps-APIs
 
 The Kubeapps APIs service provides a pluggable, gRPC-based API service enabling the Kubeapps UI (or other clients) to interact with different Kubernetes packaging formats in a consistent, extensible way.
@@ -20,6 +22,20 @@ You can read more details about the architecture, implementation and getting sta
 
 Chart repositories in Kubeapps are managed with a `CustomResourceDefinition` called `apprepositories.kubeapps.com`. Each repository added to Kubeapps is an object of type `AppRepository` and the `apprepository-controller` will watch for changes on those types of objects to update the list of available charts to deploy.
 
-### `asset-syncer`
+Please refer to the [Kubeapps Apprepository Controller Developer Guide](../reference/developer/apprepository-controller.md) for the developer setup.
+
+### asset-syncer
 
 The `asset-syncer` component is a tool that scans a Helm chart repository and populates chart metadata in a database. This metadata is then served by the Helm plugin of the `kubeapps-apis` component. Check more details about the implementation in this [document](../reference/developer/asset-syncer.md).
+
+### pinniped-proxy
+
+The `pinniped-proxy` service is an optional component that proxies incoming requests with an `Authorization: Bearer token` header, exchanging the token via the pinniped aggregate API for x509 short-lived client certificates, before forwarding the request onwards to the destination k8s API server.Check more details about the implementation in this [document](../reference/developer/pinniped-proxy.md).
+
+Please refer to the [Kubeapps Pinniped Proxy Developer Guide](../reference/developer/pinniped-proxy.md) for the developer setup.
+
+### oci-catalog
+
+The `oci-catalog` service is an optional component that enables Kubeapps to display a catalog of apps for an OCI registry or a namespace of an OCI registry. The proposed implementation is for a stateless gRPC micro-service that can be run (though is not restricted to run) as a side-car of existing the asset-syncer job to provide lists of repositories for a (namespaced) registry, regardless of the registry provider.
+
+Please refer to the [Kubeapps OCI Catalog Developer Guide](../reference/developer/oci-catalog.md) for the developer setup.
diff --git a/site/content/docs/latest/background/multicluster.md b/site/content/docs/latest/background/multicluster.md
@@ -1,14 +1,14 @@
 # Multicluster mode on Kubeapps
 
-Kubeapps is a tool for managing applications in Kubernetes clusters. Initially it was possible to work only in a single cluster, but with the implementation of the [proposal for multicluster support in Kubeapps](https://github.com/vmware-tanzu/kubeapps/blob/main/site/content/docs/latest/reference/proposals/multi-cluster-support.md), this is possible also in additional clusters.
+Kubeapps is a tool for managing applications in Kubernetes clusters. Initially it was possible to work only in a single cluster, but with the implementation of the [proposal for multicluster support in Kubeapps](../reference/proposals/multi-cluster-support.md), this is possible also in additional clusters.
 
 As a global overview, multicluster mode is based on a _default cluster_ (the one acting as orchestrator, with Kubeapps installed on it) and _additional clusters_ (target clusters without Kubeapps, where apps will be installed). Actions are performed by users in the default cluster but results are applied in a chosen additional cluster.
 
 ## Requirements for multiclustering
 
-The main requirement for working in multicluster mode is that users can be authenticated with multiple clusters using the same credentials. This is usually achieved by sharing the same OIDC client, or having the OIDC provider configured so that tokens in one cluster are allowed to include the client-ids used by the other clusters. OIDC setup can be done directly in K8s API server (with `--oidc*` flags) or [using an OIDC provider with Pinniped](https://github.com/vmware-tanzu/kubeapps/blob/main/site/content/docs/latest/howto/OIDC/using-an-OIDC-provider-with-pinniped.md).
+The main requirement for working in multicluster mode is that users can be authenticated with multiple clusters using the same credentials. This is usually achieved by sharing the same OIDC client, or having the OIDC provider configured so that tokens in one cluster are allowed to include the client-ids used by the other clusters. OIDC setup can be done directly in K8s API server (with `--oidc*` flags) or [using an OIDC provider with Pinniped](../howto/OIDC/using-an-OIDC-provider-with-pinniped.md).
 
-For more information on requirements and how to get Kubeapps working in multicluster mode, read the [how-to Configuring Kubeapps for multiple clusters](https://github.com/vmware-tanzu/kubeapps/blob/main/site/content/docs/latest/howto/deploying-to-multiple-clusters.md).
+For more information on requirements and how to get Kubeapps working in multicluster mode, read the [how-to Configuring Kubeapps for multiple clusters](../howto/deploying-to-multiple-clusters.md).
 
 ## Features
 

diff --git a/site/content/docs/latest/howto/basic-form-support.md b/site/content/docs/latest/howto/basic-form-support.md
@@ -1,3 +1,11 @@
 # Basic Form Support
 
 **NOTE:** Support for the basic form support feature had to be removed in v2.6.0 when the Bitnami catalog updated to include standard json schema files for each chart. We hope to re-enable the ability to define basic forms for users (see [#5988](https://github.com/vmware-tanzu/kubeapps/issues/5988)) rather than the current display of all fields from the values.yaml.
+
+In the meanwhile, have a look at the [how to use the dashboard documentation](./dashboard.md#deploy-an-application).
+
+<!-- TODO(agamez): piece of docs requiring update. Reason: add docs around the new feature -->
+<!--
+    https://github.com/vmware-tanzu/kubeapps/issues/5982
+    https://github.com/vmware-tanzu/kubeapps/issues/5499
+ -->
diff --git a/site/content/docs/latest/howto/custom-form-component-support.md b/site/content/docs/latest/howto/custom-form-component-support.md
@@ -3,3 +3,11 @@
 This is an extension to the [basic form support](./basic-form-support.md#basic-form-support)
 
 **NOTE:** Support for the basic form support feature had to be removed in v2.6.0 when the Bitnami catalog updated to include standard json schema files for each chart and as a result, also for the custom form component support. We hope to re-enable the ability to define basic forms for users (see [#5988](https://github.com/vmware-tanzu/kubeapps/issues/5988)) rather than the current display of all fields from the values.yaml.
+
+In the meanwhile, have a look at the [how to use the dashboard documentation](./dashboard.md#deploy-an-application).
+
+<!-- TODO(agamez): piece of docs requiring update. Reason: add docs around the new feature -->
+<!--
+    https://github.com/vmware-tanzu/kubeapps/issues/5982
+    https://github.com/vmware-tanzu/kubeapps/issues/5499
+ -->
diff --git a/site/content/docs/latest/howto/deploying-to-multiple-clusters.md b/site/content/docs/latest/howto/deploying-to-multiple-clusters.md
@@ -1,5 +1,7 @@
 # Configuring Kubeapps for multiple clusters
 
+<!-- TODO(agamez): piece of docs requiring update. Reason: screenshots using old Kubeapps logo -->
+
 It is now possible to configure Kubeapps to target other clusters when deploying a chart, in addition to the cluster on which Kubeapps is itself deployed.
 
 Once configured, you can select the cluster to which you are deploying in the same way that you can already select the namespace to which you are deploying:

diff --git a/site/content/docs/latest/reference/developer/README.md b/site/content/docs/latest/reference/developer/README.md
@@ -17,3 +17,15 @@ See the [Kubeapps APIs Service Developer Guide](kubeapps-apis.md) for more infor
 The `asset-syncer` component is a tool that scans a Helm chart repository and populates chart metadata in the database. This metadata is then served by the `kubeapps-apis` component.
 
 Please refer to the [Kubeapps asset-syncer Developer Guide](asset-syncer.md) for the developer setup.
+
+## pinniped-proxy
+
+The `pinniped-proxy` service is an optional component that proxies incoming requests with an `Authorization: Bearer token` header, exchanging the token via the pinniped aggregate API for x509 short-lived client certificates, before forwarding the request onwards to the destination k8s API server.
+
+Please refer to the [Kubeapps pinniped-proxy Developer Guide](pinniped-proxy.md) for the developer setup.
+
+## oci-catalog
+
+The `oci-catalog` service is an optional component that enables Kubeapps to display a catalog of apps for an OCI registry or a namespace of an OCI registry. The proposed implementation is for a stateless gRPC micro-service that can be run (though is not restricted to run) as a side-car of existing the asset-syncer job to provide lists of repositories for a (namespaced) registry, regardless of the registry provider.
+
+Please refer to the [Kubeapps oci-catalog Developer Guide](oci-catalog.md) for the developer setup.
diff --git a/site/content/docs/latest/reference/developer/apprepository-controller.md b/site/content/docs/latest/reference/developer/apprepository-controller.md
@@ -24,10 +24,10 @@ Based off the [Kubernetes Sample Controller](https://github.com/kubernetes/sampl
 
 - [Git](https://git-scm.com/)
 - [Make](https://www.gnu.org/software/make/)
-- [Go programming language](https://golang.org/dl/)
-- [Docker CE](https://www.docker.com/community-edition)
-- [Kubernetes cluster (v1.8+)](https://kubernetes.io/docs/setup/)
-- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+- [Go programming language](https://go.dev/dl/)
+- [Docker](https://docs.docker.com/engine/install/)
+- [Kubernetes cluster](https://kubernetes.io/docs/setup/)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
 - [Telepresence](https://telepresence.io)
   - _Telepresence is not a hard requirement, but is recommended for a better developer experience_
 

diff --git a/site/content/docs/latest/reference/developer/asset-syncer.md b/site/content/docs/latest/reference/developer/asset-syncer.md
@@ -6,10 +6,11 @@ The `asset-syncer` component is a tool that scans a Helm chart repository and po
 
 - [Git](https://git-scm.com/)
 - [Make](https://www.gnu.org/software/make/)
-- [Go programming language](https://golang.org/dl/)
-- [Docker CE](https://www.docker.com/community-edition)
-- [Kubernetes cluster (v1.8+)](https://kubernetes.io/docs/setup/). [Minikube](https://github.com/kubernetes/minikube) is recommended.
-- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+- [Go programming language](https://go.dev/dl/)
+- [Docker](https://docs.docker.com/engine/install/)
+- [Kubernetes cluster](https://kubernetes.io/docs/setup/).
+  - [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) is recommended.
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
 - [Telepresence](https://telepresence.io)
   - _Telepresence is not a hard requirement, but is recommended for a better developer experience_
 

diff --git a/site/content/docs/latest/reference/developer/build.md b/site/content/docs/latest/reference/developer/build.md
@@ -6,9 +6,9 @@ This guide explains how to build Kubeapps.
 
 - [Git](https://git-scm.com/)
 - [Make](https://www.gnu.org/software/make/)
-- [Go programming language](https://golang.org/)
+- [Go programming language](https://go.dev/dl/)
 - [kubecfg](https://github.com/ksonnet/kubecfg)
-- [Docker CE](https://www.docker.com/community-edition)
+- [Docker](https://docs.docker.com/engine/install/)
 
 ## Download kubeapps source code
 

diff --git a/site/content/docs/latest/reference/developer/dashboard.md b/site/content/docs/latest/reference/developer/dashboard.md
@@ -5,11 +5,12 @@ The dashboard is the main UI component of the Kubeapps project. Written in JavaS
 ## Prerequisites
 
 - [Git](https://git-scm.com/)
-- [Node 12.x](https://nodejs.org/)
+- [Node](https://nodejs.org/)
 - [Yarn](https://yarnpkg.com)
-- [Kubernetes cluster (v1.8+)](https://kubernetes.io/docs/setup/)
-- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
-- [Docker CE](https://www.docker.com/community-edition)
+- [Kubernetes cluster](https://kubernetes.io/docs/setup/)
+  - [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) is recommended.
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
+- [Docker](https://docs.docker.com/engine/install/)
 - [Telepresence](https://telepresence.io)
   - _Telepresence is not a hard requirement, but is recommended for a better developer experience_
 

diff --git a/site/content/docs/latest/reference/developer/kubeapps-apis.md b/site/content/docs/latest/reference/developer/kubeapps-apis.md
@@ -4,10 +4,14 @@ The Kubeapps APIs service provides a pluggable, gRPC-based API service enabling
 
 The Kubeapps APIs service is bundled with three packaging plugins providing support for the Helm, Carvel and Flux packaging formats, enabling users to browse and install packages of different formats.
 
+<!-- TODO(agamez): piece of docs requiring update. Reason: screenshots using old Kubeapps logo -->
+
 ![Kubeapps with packaging plugins](../../img/kubeapps-apis/packages-plugins.png)
 
 In addition to these three packaging plugins, the Kubeapps APIs service is also bundled with a Kubernetes resources plugin that removes the long-standing requirement for the Kubeapps UI to talk directly with the Kubernetes API server. With this change, a user with the required RBAC can request, for example, Kubernetes resources for a specific installed package only:
 
+<!-- TODO(agamez): piece of docs requiring update. Reason: screenshots using old Kubeapps logo -->
+
 ![Kubeapps with resources plugins](../../img/kubeapps-apis/resources-plugin.png)
 
 ## Architectural overview

diff --git a/site/content/docs/latest/reference/developer/oci-catalog.md b/site/content/docs/latest/reference/developer/oci-catalog.md
@@ -0,0 +1,45 @@
+# OCI Catalog Developer Guide
+
+> This section is still in development.
+
+<!-- TODO(agamez): piece of docs requiring update. Reason: new section-->
+
+## Prerequisites
+
+- [Git](https://git-scm.com/)
+- [Rust programming language](https://www.rust-lang.org/tools/install)
+
+## Running in development
+
+[`cargo`](https://doc.rust-lang.org/cargo/) is the Rust package manager tool is used for most development activities. Assuming you are already in the `cmd/oci-catalog` directory, you can always compile and run the executable with:
+
+```bash
+cargo run
+```
+
+and pass command-line options to the executable after a double-dash, for example:
+
+```bash
+cargo run -- --help
+   Compiling oci-catalog v0.1.0 (/mnt/c/repos/kubeapps/cmd/oci-catalog)
+    Finished dev [unoptimized + debuginfo] target(s) in 1m 47s
+     Running `target/debug/oci-catalog --help`
+A service that returns catalog information for an OCI repository.
+
+The OCI Catalog service uses a strategy pattern to enable listing catalog information for different OCI provider registries, until a standard is set for requesting namespaced repositories of a registry in the OCI Distribution specification.
+
+Usage: oci-catalog [OPTIONS]
+
+Options:
+  -p, --port <PORT>
+          Specify the port on which oci-catalog gRPC service listens.
+
+          [env: OCI_CATALOG_PORT=]
+          [default: 50001]
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
+```
diff --git a/site/content/docs/latest/reference/developer/using-makefiles.md b/site/content/docs/latest/reference/developer/using-makefiles.md
@@ -21,6 +21,8 @@ make kubeapps/dashboard
 make kubeapps/apprepository-controller
 make kubeapps/kubeapps-apis
 make kubeapps/asset-syncer
+make kubeapps/pinniped-proxy
+make kubeapps/oci-catalog
 ```
 
 > You can set the image tag manually: `IMAGE_TAG=myTag make`

diff --git a/site/content/docs/latest/reference/testing/testing-environment.md b/site/content/docs/latest/reference/testing/testing-environment.md
@@ -12,8 +12,9 @@ This guide aims to provide the instructions to easily setup the environment to t
 
 ## Prerequisites
 
-- [Kubernetes cluster (v1.12+)](https://kubernetes.io/docs/setup/).
-- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+- [Kubernetes cluster](https://kubernetes.io/docs/setup/).
+  - [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) is recommended.
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl).
 - [Helm client](https://helm.sh/docs/intro/install/).
 
 ## Environment setup

diff --git a/site/content/docs/latest/tutorials/getting-started.md b/site/content/docs/latest/tutorials/getting-started.md
@@ -24,7 +24,7 @@ This guide walks you through the process of deploying Kubeapps for your cluster
 
 ## Pre-requisites
 
-- Kubeapps assumes a working Kubernetes cluster (v1.21+), as well as the [`helm`](https://helm.sh/docs/intro/install/) (v3.2.0+) and [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line interfaces installed and configured to talk to your Kubernetes cluster.
+- Kubeapps assumes a working Kubernetes cluster (v1.21+), as well as the [`helm`](https://helm.sh/docs/intro/install/) (v3.2.0+) and [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line interfaces installed and configured to talk to your Kubernetes cluster.
 
 - Kubeapps has been tested with Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), kind, minikube and Docker for Desktop Kubernetes.
 
@@ -50,6 +50,10 @@ The above commands deploys Kubeapps into the `kubeapps` namespace in your cluste
 
 For any user-facing installation you should [configure an OAuth2/OIDC provider](./using-an-OIDC-provider.md) to enable secure user authentication with Kubeapps and the cluster, but this is quite an overhead to simply try out Kubeapps. Instead, for a simpler way to try out Kubeapps for personal learning, we can create a Kubernetes service account and use that API token to authenticate with the Kubernetes API server via Kubeapps:
 
+> **NOTE** It's not recommended to assign users the `cluster-admin` role for Kubeapps production usage. Please refer to the [Access Control](../howto/access-control.md) documentation to configure fine-grained access control for users.
+
+### On Linux/macOS
+
 ```bash
 kubectl create --namespace default serviceaccount kubeapps-operator
 kubectl create clusterrolebinding kubeapps-operator --clusterrole=cluster-admin --serviceaccount=default:kubeapps-operator
@@ -65,9 +69,24 @@ type: kubernetes.io/service-account-token
 EOF
 ```
 
-> **NOTE** It's not recommended to assign users the `cluster-admin` role for Kubeapps production usage. Please refer to the [Access Control](../howto/access-control.md) documentation to configure fine-grained access control for users.
+### On Windows
+
+```powershell
+kubectl create --namespace default serviceaccount kubeapps-operator
+kubectl create clusterrolebinding kubeapps-operator --clusterrole=cluster-admin --serviceaccount=default:kubeapps-operator
+@"
+apiVersion: v1
+kind: Secret
+metadata:
+  name: kubeapps-operator-token
+  namespace: default
+  annotations:
+    kubernetes.io/service-account.name: kubeapps-operator
+type: kubernetes.io/service-account-token
+"@ | kubectl apply -f -
+```
 
-To retrieve the token,
+Next, to retrieve the token,
 
 ### On Linux/macOS
 

diff --git a/site/content/docs/latest/tutorials/operators.md b/site/content/docs/latest/tutorials/operators.md
@@ -6,7 +6,7 @@ In this tutorial we will be using the [Operator Lifecycle Manager (OLM)](https:/
 
 ## Prerequisites
 
-Kubeapps assumes a working Kubernetes cluster (v1.12+) and [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed and configured to talk to your Kubernetes cluster. Users following this tutorial require to have admin privileges in the cluster in order to install and manage Operators.
+Kubeapps assumes a working Kubernetes cluster (v1.12+) and [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) installed and configured to talk to your Kubernetes cluster. Users following this tutorial require to have admin privileges in the cluster in order to install and manage Operators.
 
 ## Step 1: Enable Operators support in Kubeapps