Merge pull request #1309 from inteon/restructure_top_level_v0

Restructure top-level menu

.spelling

@@ -642,6 +642,7 @@ PrivateCA
 structs
 klog
 relabelings
+kustomize
 
 FlorianLiebhart
 cypres

content/docs/concepts/certificate.md

@@ -60,31 +60,6 @@ which contains the following explanation:
 > assumption that the remote end must already possess it in order to
 > validate it in any case.
 
-<div className="alert">
-
-When configuring a client to connect to a TLS server with a serving certificate that is signed by a private CA,
-you will need to provide the client with the CA certificate in order for it to verify the server.
-`ca.crt` will likely contain the certificate you need to trust,
-but __do not mount the same `Secret` as the server__ to access `ca.crt`.
-This is because:
-
-1. That `Secret` also contains the private key of the server, which should only be accessible to the server.
-   You should use RBAC to ensure that the `Secret` containing the serving certificate and private key are only accessible to Pods that need it.
-2. Rotating CA certificates safely relies on being able to have both the old and new CA certificates trusted at the same time.
-   By consuming the CA directly from the source, this isn't possible;
-   you'll be _forced_ to have some down-time in order to rotate certificates.
-
-When configuring the client you should independently choose and fetch the CA certificates that you want to trust.
-Download the CA out of band and store it in a `Secret` or `ConfigMap` separate from the `Secret` containing the server's private key and certificate.
-
-This ensures that if the material in the `Secret` containing the server key and certificate is tampered with,
-the client will fail to connect to the compromised server.
-
-The same concept also applies when configuring a server for mutually-authenticated TLS;
-don't give the server access to Secret containing the client certificate and private key.
-
-</div>
-
 The `dnsNames` field specifies a list of [`Subject Alternative
 Names`](https://en.wikipedia.org/wiki/Subject_Alternative_Name) to be associated
 with the certificate.

content/docs/configuration/ca.md

@@ -15,7 +15,7 @@ private key are stored inside the cluster as a Kubernetes `Secret`.
 Certificates issued by a CA issuer will not be publicly trusted and so are unlikely to be trusted
 by your applications without further configuration.
 
-Consider [trust-manager](../projects/trust-manager/README.md) for distributing your CA certificate safely
+Consider [trust-manager](../trust/trust-manager/README.md) for distributing your CA certificate safely
 across your cluster!
 
 ## Deployment

content/docs/configuration/selfsigned.md

@@ -181,7 +181,7 @@ Clients consuming `SelfSigned` certificates have _no way_ to trust them
 without already having the certificates beforehand, which can be hard to
 manage when the client is in a different namespace to the server.
 
-This limitation can be tackled by using [trust-manager](../projects/trust-manager/README.md) to distribute `ca.crt`
+This limitation can be tackled by using [trust-manager](../trust/trust-manager/README.md) to distribute `ca.crt`
 to other namespaces.
 
 There is no secure alternative to solving the problem of distributing trust stores; it's possible

content/docs/projects/README.md → content/docs/contributing/projects.md

@@ -8,24 +8,23 @@ that extend the project's functionality, and complement the core cert-manager fe
 
 These tools help with security, compliance and control.
 
-- [istio-csr](./istio-csr.md): Secure Istio service mesh with istio-csr which is
+- [istio-csr](https://github.com/cert-manager/istio-csr) ([docs](../usage/istio-csr.md)): Secure Istio service mesh with istio-csr which is
   an agent that allows for [Istio](https://istio.io) workload and control plane
   components to be secured using cert-manager.
-- [approver-policy](./approver-policy/README.md):
+- [approver-policy](https://github.com/cert-manager/approver-policy) ([docs](../policy/approval/approver-policy/README.md)):
   a cert-manager **approver** that will automatically approve or deny
   certificate requests based on defined policy.
-- [csi-driver](./csi-driver.md):
+- [csi-driver](https://github.com/cert-manager/csi-driver) ([docs](../usage/csi-driver.md)):
   a Container Storage Interface (CSI) driver plugin for Kubernetes to work along
   cert-manager. The goal for this plugin is to seamlessly request and mount
   certificate key pairs to pods. This is useful for facilitating mTLS, or
   otherwise securing connections of pods with guaranteed present certificates
   whilst having all of the features that cert-manager provides.
-- [csi-driver-spiffe](./csi-driver-spiffe.md):
+- [csi-driver-spiffe](https://github.com/cert-manager/csi-driver-spiffe) ([docs](../usage/csi-driver-spiffe.md)):
   another CSI driver plugin to work along cert-manager. This CSI driver
   transparently delivers [SPIFFE](https://spiffe.io/)
   [SVIDs](https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/#spiffe-verifiable-identity-document-svid)
   in the form of X.509 certificate key pairs to mounting Kubernetes Pods. The
   end result is all and any Pod running in Kubernetes can securely request their
   SPIFFE identity document from a Trust Domain with minimal configuration.
-- [trust-manager](./trust-manager/README.md): the easiest way to manage TLS trust bundles in Kubernetes and OpenShift clusters.
-- [trust-manager API reference](./trust-manager/api-reference.md): full documentation of the trust-manager CRD(s)
+- [trust-manager](https://github.com/cert-manager/trust-manager) ([docs](../trust/trust-manager/README.md)): the easiest way to manage TLS trust bundles in Kubernetes and OpenShift clusters.

content/docs/installation/uninstall.md

@@ -11,4 +11,4 @@ cert-manager to go to the relevant uninstall documentation.
 - [kubectl](./kubectl.md#uninstalling)
 - [helm](./helm.md#uninstalling)
 
-If you need to preserve cert-manager custom resources (`Certificate`s, `Issuer`s etc), that are not version controlled or backed up by other means, take a look at our [backup and restore guide](../tutorials/backup.md).
+If you need to preserve cert-manager custom resources (`Certificate`s, `Issuer`s etc), that are not version controlled or backed up by other means, take a look at our [backup and restore guide](../devops-tips/backup.md).

content/docs/installation/upgrading/README.md

@@ -10,7 +10,7 @@ versions, and information on things to look out for when upgrading.
 > Note: Before performing upgrades of cert-manager, it is advised to take a
 > backup of all your cert-manager resources just in case an issue occurs whilst
 > upgrading. You can read how to backup and restore cert-manager in the [backup
-> and restore](../../tutorials/backup.md) guide.
+> and restore](../../devops-tips/backup.md) guide.
 
 We recommend that you upgrade cert-manager one minor version at a time, always
 choosing the latest patch version for the minor version. You should always read

content/docs/installation/upgrading/upgrading-0.10-0.11.md

@@ -20,7 +20,7 @@ resources, will need to be updated to reflect these changes.
 This upgrade should be performed in a few steps:
 
 1. Back up existing cert-manager resources, as per the
-   [backup and restore guide](../../tutorials/backup.md).
+   [backup and restore guide](../../devops-tips/backup.md).
 
 2. [Uninstall cert-manager](../uninstall.md).
 

content/docs/installation/upgrading/upgrading-0.16-1.0.md

@@ -48,7 +48,7 @@ However you should convert the (Cluster)Issuers and delete the old CRD versions.
 
 This upgrade MUST be performed in the following sequence of steps:
 
-1. [Back up](../../tutorials/backup.md) existing cert-manager resources. See the backup section.
+1. [Back up](../../devops-tips/backup.md) existing cert-manager resources. See the backup section.
 
 2. [Uninstall cert-manager](../uninstall.md).
 

content/docs/installation/upgrading/upgrading-0.5-0.6.md

@@ -50,7 +50,7 @@ This **will not** delete the Secret resources being used by your apps.
 
 Before upgrading you will need to:
 
-1. Read and follow the [backup guide](../../tutorials/backup.md) to create a
+1. Read and follow the [backup guide](../../devops-tips/backup.md) to create a
    backup of your configuration.
 
 2. Delete the existing cert-manager Helm release (replacing 'cert-manager' with
@@ -91,7 +91,7 @@ $ helm install \
     stable/cert-manager
 ```
 
-4. Follow the steps in the [restore guide](../../tutorials/backup.md) to
+4. Follow the steps in the [restore guide](../../devops-tips/backup.md) to
    restore your configuration.
 
 5. Verify that your Issuers and Certificate resources are 'Ready':

content/docs/installation/upgrading/upgrading-0.8-0.9.md

@@ -8,7 +8,7 @@ Due to a change in the API group that cert-manager deployments use
 before applying the new version. This will cause downtime until the new version
 has been applied. No data loss will occur during this operation however it is
 always advised to backup your data during an upgrade, which you can follow
-[here](../../tutorials/backup.md). To perform this action run:
+[here](../../devops-tips/backup.md). To perform this action run:
 
 ```bash
 $ kubectl delete deployments --namespace cert-manager \

content/docs/installation/upgrading/upgrading-1.1-1.2.md

@@ -7,7 +7,7 @@ In an effort to introduce new features whilst keeping the project maintainable,
 cert-manager now only supports Kubernetes down to version `v1.16`. This means
 the `legacy` manifests have now been removed. Some users experience issues when
 upgrading the legacy `CRD`s to `v1.2`. To solve this, you could replace the `CRD`s:
-1. Backup `cert-manager` resources as described in [the docs](../../tutorials/backup.md)
+1. Backup `cert-manager` resources as described in [the docs](../../devops-tips/backup.md)
 2. Run `kubectl replace -f https://github.com/cert-manager/cert-manager/releases/download/v1.2.0/cert-manager.crds.yaml` to replace the CRDs.
 3. Follow the standard upgrade process.
 You can read more about supported Kubernetes versions