site: move non versioned docs to projectcontour.io/resources

Updates projectcontour#1619 Take a first pass through the /docs/ directory any move any documents which are not specific to a release. Also remove a few outdated docs like tls.md and zenhub.md. Signed-off-by: Dave Cheney <[email protected]>
mattalberts · Oct 14, 2019 · 921421c · 921421c
1 parent 49bc3f2
commit 921421c
Show file tree

Hide file tree

Showing 19 changed files with 127 additions and 77 deletions.
diff --git a/docs/tls.md b/docs/tls.md
diff --git a/docs/zenhub.md b/docs/zenhub.md
diff --git a/site/_config.yml b/site/_config.yml
@@ -48,8 +48,12 @@ defaults:
 repository: projectcontour/contour
 
 collections:
-  - contributors
-  - casestudies
+  resources:
+    output: true
+  contributors:
+    output: false
+  casestudies:
+    output: false
 
 # Build settings
 permalink: :title/
@@ -85,6 +89,6 @@ exclude:
   - CNAME
   - Runbook.docx
   - '*.sh'
-  - vendor/
+  - vendor
 redcarpet:
     extensions: ["no_intra_emphasis", "tables", "autolink", "strikethrough", "with_toc_data"]
diff --git a/docs/deploy-aws-nlb.md → site/_resources/deploy-aws-nlb.md b/docs/deploy-aws-nlb.md → site/_resources/deploy-aws-nlb.md
@@ -1,4 +1,7 @@
-# Contour Deployment on AWS with NLB
+---
+title: Contour Deployment on AWS with NLB
+layout: page
+---
 
 This is an advanced deployment guide to configure Contour on AWS with the [Network Load Balancer (NLB)][1].
 This configuration has several advantages:
@@ -36,6 +39,6 @@ You can now test your NLB.
   - Notice that Envoy fills out `X-Forwarded-For`, because it was the first to see the traffic directly from the browser.
 
 [1]: https://aws.amazon.com/blogs/aws/new-network-load-balancer-effortless-scaling-to-millions-of-requests-per-second/
-[2]: deploy-options.md#test
+[2]: {% link _resources/deploy-options.md %}#test
 [3]: https://github.com/kubernetes/kubernetes/issues/52173
-[4]: ../CONTRIBUTING.md
+[4]: {{ site.github.repository_url }}/tree/master//CONTRIBUTING.md
diff --git a/docs/deploy-options.md → site/_resources/deploy-options.md b/docs/deploy-options.md → site/_resources/deploy-options.md
@@ -1,4 +1,7 @@
-# Deployment and testing
+---
+title: Deployment options
+layout: page
+---
 
 The [README](../README.md#get-started) shows you a simple way to get started with Contour on your cluster.
 This topic explains the details and shows you additional options.
@@ -37,7 +40,7 @@ contour   10.106.53.14   a47761ccbb9ce11e7b27f023b7e83d33-2036788482.ap-southeas
 Depending on your cloud provider, the `EXTERNAL-IP` value is an IP address, or, in the case of Amazon AWS, the DNS name of the ELB created for Contour. Keep a record of this value.
 
 Note that if you are running an Elastic Load Balancer (ELB) on AWS, you must add more details to your configuration to get the remote address of your incoming connections.
-See the [instructions for enabling the PROXY protocol.](proxy-proto.md).
+See the [instructions for enabling the PROXY protocol.]({% link _resources/proxy-proto.md %}).
 
 #### Minikube
 

diff --git a/docs/github.md → site/_resources/github.md b/docs/github.md → site/_resources/github.md
@@ -1,4 +1,7 @@
-# GitHub workflows
+---
+title: GitHub contribution workflow
+layout: page
+---
 
 This document outlines how we use GitHub.
 
@@ -14,9 +17,12 @@ Issues which are not assigned to the current milestone _should not be worked on_
 
 This project has three levels of priority:
 
-- p0 - Must fix immediately. This is reserved for bugs and security issues. A milestone cannot ship with open p0 issues.
-- p1 - Should be done. p1 issues assigned to a milestone _should_ be completed during that milestone.
-- p2 - May be done. p2 issues assigned to a milestone _may_ be completed during that milestone if time permits. 
+- p0 - Must fix immediately.
+This is reserved for bugs and security issues. A milestone cannot ship with open p0 issues.
+- p1 - Should be done.
+p1 issues assigned to a milestone _should_ be completed during that milestone.
+- p2 - May be done.
+p2 issues assigned to a milestone _may_ be completed during that milestone if time permits. 
 
 Issues without a priority are _unprioritised_. Priority will be assigned by a PM or release manager during issue triage.
 
@@ -71,7 +77,6 @@ If there is no `Updates` or `Fixes` line in the PR the review will, with the exc
 
 [Further reading](https://dave.cheney.net/2019/02/18/talk-then-code)
 
-
 ## Help wanted and good first issues
 
 The `help wanted` and `good first issue` tags _may_ be assigned to issues _in the current milestone_.

diff --git a/docs/grpc-tls-howto.md → site/_resources/grpc-tls-howto.md b/docs/grpc-tls-howto.md → site/_resources/grpc-tls-howto.md
@@ -1,4 +1,7 @@
-# Generating example gRPC TLS certificates
+---
+title: gRPC TLS configuration
+layout: page
+---
 
 ## Outcomes
 
@@ -9,7 +12,7 @@ The outcome of this is that we will have three Secrets available in the `project
 
 ### Ways you can get the certificates into your cluster
 
-- Deploy the Job from [certgen.yaml](../examples/contour/02-job-certgen.yaml).
+- Deploy the Job from [certgen.yaml]({{ site.github.repository_url }}/tree/master/examples/contour/02-job-certgen.yaml).
 This will run `contour certgen --kube` for you.
 - Run `contour certgen --kube` locally.
 - Run the manual procedure below.
@@ -41,7 +44,7 @@ Then, we need to generate a keypair for Contour. First, we make a new private ke
 openssl genrsa -out certs/contourkey.pem 2048
 ```
 
-Then, we create a CSR and have our CA sign the CSR and issue a cert. This uses the file [_integration/cert-contour.ext](./_integration/cert-contour.ext), which ensures that at least one of the valid names of the certificate is the bareword `contour`. This is required for the handshake to succeed, as `contour bootstrap` configures Envoy to pass this as the SNI for the connection.
+Then, we create a CSR and have our CA sign the CSR and issue a cert. This uses the file [_integration/cert-contour.ext]({{ site.github.repository_url }}/tree/master/_integration/cert-contour.ext), which ensures that at least one of the valid names of the certificate is the bareword `contour`. This is required for the handshake to succeed, as `contour bootstrap` configures Envoy to pass this as the SNI for the connection.
 
 ```
 openssl req -new -key certs/contourkey.pem \
@@ -79,7 +82,7 @@ openssl x509 -req -in certs/envoy.csr \
     -extfile _integration/cert-envoy.ext
 ```
 
-Like the contour cert, this CSR uses the file [_integration/cert-envoy.ext](./_integration/cert-envoy.ext). However, in this case, there are no special names required.
+Like the contour cert, this CSR uses the file [_integration/cert-envoy.ext]({{ site.github.repository_url }}/tree/master/_integration/cert-envoy.ext). However, in this case, there are no special names required.
 
 ### Putting the certs in the cluster
 
@@ -93,6 +96,6 @@ kubectl create secret -n projectcontour tls envoycert --key=./certs/envoykey.pem
 
 Note that we don't put the CA **key** into the cluster, there's no reason for that to be there, and that would create a security problem. That also means that the `cacert` secret can't be a `tls` type secret, as they must be a keypair.
 
-# Conclusion
+ # Conclusion
 
 Once this process is done, the certificates will be present as Secrets in the `projectcontour` namespace, as required by `examples/contour`.
diff --git a/docs/how-we-work.md → site/_resources/how-we-work.md b/docs/how-we-work.md → site/_resources/how-we-work.md
@@ -1,3 +1,8 @@
+---
+title: How we work
+layout: page
+---
+
 This page captures how we work on Contour.
 
 - When you pick up an issue, assign it to yourself.

diff --git a/docs/ingressroute-to-httpproxy.md → site/_resources/ingressroute-to-httpproxy.md b/docs/ingressroute-to-httpproxy.md → site/_resources/ingressroute-to-httpproxy.md
@@ -1,8 +1,11 @@
-# IngressRoute to HTTPProxy
+---
+title: IngressRoute to HTTPProxy
+layout: page
+---
 
 This document describes the differences between IngressRoute and HTTPProxy.
 It is intended for Contour users who have existing IngressRoute resources they wish to migrate to HTTPProxy.
-It is not intended a comprehensive documentation of HTTPProxy, for that please see the [`HTTPProxy` documentation](./httpproxy.md).
+It is not intended a comprehensive documentation of HTTPProxy, for that please see the [`HTTPProxy` documentation]({{ site.github.repository_url }}/tree/master/docs/httpproxy.md).
 
 _Note: IngressRoute is deprecated and will be removed after Contour 1.0 ships in November._
 
@@ -18,6 +21,7 @@ apiVersion: contour.heptio.com/v1beta1
 kind: IngressRoute
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: HTTPProxy
@@ -28,6 +32,7 @@ kind: HTTPProxy
 No change.
 
 Before:
+
 ```yaml
 apiVersion: contour.heptio.com/v1beta1
 kind: IngressRoute
@@ -41,6 +46,7 @@ spec:
       secretName: tlssecret
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: HTTPProxy
@@ -100,6 +106,7 @@ The group and version of the TLSCertificateDelegation CRD have changed.
 `contour.heptio.com/v1beta1.TLSCertificateDelegation` will be removed after Contour 1.0 ships in November.
 
 Before:
+
 ```yaml
 apiVersion: contour.heptio.com/v1beta1
 kind: TLSCertificateDelegation
@@ -113,6 +120,7 @@ spec:
       - example-com
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: TLSCertificateDelegation
@@ -130,9 +138,10 @@ spec:
 
 HTTPProxy offers additional ways to match incoming requests to routes.
 This document covers the conversion between the routing offered in IngressRoute and HTTPProxy.
-For a broader discussion of HTTPProxy routing, see the [Routing section of the HTTPProxy documentation](./httpproxy.md#Routing).
+For a broader discussion of HTTPProxy routing, see the [Routing section of the HTTPProxy documentation]({{ site.github.repository_url }}/tree/master/docs/httpproxy.md#Routing).
 
 Before:
+
 ```yaml
 apiVersion: contour.heptio.com/v1beta1
 kind: IngressRoute
@@ -153,6 +162,7 @@ spec:
           port: 80
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: HTTPProxy
@@ -188,6 +198,7 @@ No change.
 `routes.timeoutPolicy.request` has been renamed to `routes.timeoutPolicy.response` to more accurately reflect is the timeout for the response.
 
 Before:
+
 ```yaml
 apiVersion: contour.heptio.com/v1beta1
 kind: IngressRoute
@@ -206,6 +217,7 @@ spec:
       port: 80
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: HTTPProxy
@@ -237,6 +249,7 @@ See #899
 Per service load balancing strategy has moved to a per route strategy that applies to all services for that route.
 
 Before:
+
 ```yaml
 apiVersion: contour.heptio.com/v1beta1
 kind: IngressRoute
@@ -257,6 +270,7 @@ spec:
           strategy: WeightedLeastRequest
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: HTTPProxy
@@ -285,6 +299,7 @@ See above.
 Per service health check has moved to a per route health check that applies to all services for that route.
 
 Before:
+
 ```yaml
 apiVersion: contour.heptio.com/v1beta1
 kind: IngressRoute
@@ -309,6 +324,7 @@ spec:
           port: 80
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: HTTPProxy
@@ -353,9 +369,10 @@ As we explored the design of the next revision of IngressRoute the tight couplin
 
 This Gordian Knot was severed by decoupling the inclusion of one document into its parent from the facility to place restrictions on what route matching conditions could be specified in that document.
 The former we call _inclusion_, the latter are known as _conditions_.
-This section discusses conversion from delegation to inclusion, please see the [`HTTPProxy` documentation](./httpproxy.md) for a discussion of conditions.
+This section discusses conversion from delegation to inclusion, please see the [`HTTPProxy` documentation]({{ site.github.repository_url }}/tree/master/docs/httpproxy.md) for a discussion of conditions.
 
 Before:
+
 ```yaml
 # root.ingressroute.yaml
 apiVersion: contour.heptio.com/v1beta1
@@ -394,6 +411,7 @@ spec:
           port: 80
 ```
 After:
+
 ```yaml
 apiVersion: projectcontour.io/v1
 kind: HTTPProxy
@@ -451,7 +469,7 @@ Orphaned status will be reported on _child_ HTTPProxy objects that are not inclu
 
 The `--ingressroute-root-namespace` flag has been renamed to `--root-namespaces` for obvious reasons.
 The old name is deprecated and will be removed after Contour 1.0 is released.
-See the [upgrading documentation](./upgrading.md) for more information on upgrading from Contour 0.15.0 to 1.0.0-beta.1
+See the [upgrading documentation]({% link _resources/upgrading.md %}) for more information on upgrading from Contour 0.15.0 to 1.0.0-beta.1
 
 ### TCP Proxying
 

diff --git a/docs/prometheus.md → site/_resources/prometheus.md b/docs/prometheus.md → site/_resources/prometheus.md
@@ -1,4 +1,7 @@
-# Prometheus
+---
+title: Prometheus
+layout: page
+---
 
 Contour and Envoy expose metrics that can be scraped with Prometheus. By
 default, annotations to gather them are in all the `deployment` yamls and they

diff --git a/docs/proxy-proto.md → site/_resources/proxy-proto.md b/docs/proxy-proto.md → site/_resources/proxy-proto.md
@@ -1,4 +1,7 @@
-# EC2 ELB PROXY protocol support
+---
+title: PROXY v1/v2 protocol support
+layout: page
+---
 
 If you deploy Contour as a Deployment or Daemonset, you will likely use a `type: LoadBalancer` Service to request an [external load balancer][1] from your hosting provider.
 If you use the Elastic Load Balancer (ELB) service from Amazon's EC2, you need to perform a couple of additional steps to enable the [PROXY][0] protocol. Here's why:

diff --git a/docs/making-a-release.md → site/_resources/release-process.md b/docs/making-a-release.md → site/_resources/release-process.md
@@ -1,4 +1,7 @@
-# Making a Contour release
+---
+title: Release process
+layout: page
+---
 
 This page documents the process for releasing a new version of Contour.
 

diff --git a/docs/resource_limits.md → site/_resources/resource_limits.md b/docs/resource_limits.md → site/_resources/resource_limits.md
@@ -1,4 +1,7 @@
-# Contour / Envoy Resource Limits
+---
+title: Contour / Envoy Resource Limits
+layout: page
+---
 
 ## Performance Testing Contour / Envoy
 
@@ -156,4 +159,4 @@ Verify the Memory & CPU usage with varying numbers of services, IngressRoute res
     <td align="right">225</td>
     <td align="right">40%</td>
   </tr>
-</table>
+</table>
diff --git a/docs/support.md → site/_resources/support.md b/docs/support.md → site/_resources/support.md
@@ -1,11 +1,14 @@
-# Supported version policy
+---
+title: Supported version policy
+layout: page
+---
 
 This document describes which versions of Contour are supported by the Contour team.
 
 ## Stable release
 
 Only the latest stable release is supported.
-The latest stable release is identified by the [Docker tag `:latest`](../tagging.md).
+The latest stable release is identified by the [Docker tag `:latest`]({% link _resources/tagging.md %}).
 
 When required we may release a patch release to address security issues, serious problems with no suitable workaround, or documentation issues.
 At that point the patch release will become the :latest stable release.