From e2c780d00c53313a627c447958119656be98c326 Mon Sep 17 00:00:00 2001 From: Jason Madigan Date: Tue, 12 Sep 2023 10:23:33 +0100 Subject: [PATCH 1/2] updating nav --- docs/getting-started.md | 37 +++++++++++ docs/index.md | 3 + mkdocs.yml | 132 +++++++++++++++++++++------------------- 3 files changed, 109 insertions(+), 63 deletions(-) create mode 100644 docs/getting-started.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..9bdb3c19 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,37 @@ +## Getting started with Kuadrant locally + +We have a quickstart setup script below which will setup and install Kuadrant and its components (Authorino, Limitador and the Multicluster Gateway Controller) into some local `kind` clusters for evaluation. +### Prerequisites + +- [Docker](https://docs.docker.com/engine/install/) +- [Kind](https://kind.sigs.k8s.io/) +- [Kubectl](https://kubernetes.io/docs/tasks/tools/) +- OpenSSL >= 3 +- AWS account with Route 53 enabled +- [Docker Mac Net Connect](https://github.com/chipmk/docker-mac-net-connect) (macOS users only) + +### Config + +One of Kuadrant's components, the Multicluster Gateway Controller, programs DNS to provide multicluster connectivity and load balaning. As part of setting this up, you'll need to export some environment variables with the keys listed below. Fill in your own values as appropriate. Note that you will need to have created a root domain in AWS using Route 53: + +| Env Var | Example Value | Description | +|------------------------------|-----------------------------|----------------------------------------------------------------| +| `MGC_ZONE_ROOT_DOMAIN` | `jbloggs.hcpapps.net` | Hostname for the root Domain | +| `MGC_AWS_DNS_PUBLIC_ZONE_ID` | `Z01234567US0IQE3YLO00` | AWS Route 53 Zone ID for specified `MGC_ZONE_ROOT_DOMAIN` | | +| `MGC_AWS_ACCESS_KEY_ID` | `AKIA1234567890000000` | Access Key ID, with access to resources in Route 53 | +| `MGC_AWS_SECRET_ACCESS_KEY` | `Z01234567US0000000` | Access Secret Access Key, with access to resources in Route 53 | +| `MGC_AWS_REGION` | `eu-west-1` | AWS Region | +| `MGC_SUB_DOMAIN` | `myapp.jbloggs.hcpapps.net` | AWS Region | + +>Alternatively, to set defaults, add the above environment variables to your `.zshrc` or `.bash_profile`. + +### Set Up Clusters and Kuadrant + + ```bash + curl https://raw.githubusercontent.com/kuadrant/multicluster-gateway-controller/main/hack/quickstart-setup.sh | bash + ``` + +### What's Next + +* [Multicluster Gateways walkthrough](how-to/multicluster-gateways-walkthrough.md) +* [Kuadrant Documentation](https://docs.kuadrant.io). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 22ca3457..fe4c9f97 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,9 @@ Kuadrant brings together [Gateway API](https://gateway-api.sigs.k8s.io/) and [Open Cluster Management](https://open-cluster-management.io/) to help you scale, load-balance and secure your Ingress Gateways as a key part of your application connectivity, in the single or multi-cluster environment. +# Getting Started +To quickly get started with Kuadrant locally, see our [Getting Started guide](getting-started.md). + ## Single-cluster Kuadrant can be used to protect ingress gateways based on [Gateway API](https://gateway-api.sigs.k8s.io/)[^1] with policy enforcement (rate limit and auth) in a Kuberentes cluster. diff --git a/mkdocs.yml b/mkdocs.yml index 8fa25481..7041a1f9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,25 +66,34 @@ plugins: imports: - /rfcs/* nav: - - 'Getting Started': index.md - - 'Kuadrant Operator': - - 'Overview': kuadrant-operator/README.md - - 'How-to': - - kuadrant-operator/doc/user-guides/simple-rl-for-app-developers.md - - kuadrant-operator/doc/user-guides/gateway-rl-for-cluster-operators.md - - kuadrant-operator/doc/user-guides/authenticated-rl-for-app-developers.md - - kuadrant-operator/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md - - kuadrant-operator/doc/logging.md - - 'Reference': + - 'Overview': index.md + - 'Getting Started': getting-started.md + - 'Installation': + - 'Control Plane installation with Existing OCM': multicluster-gateway-controller/docs/installation/control-plane-installation.md + - 'Service Protection installation with Existing OCM': multicluster-gateway-controller/docs/installation/service-protection-installation.md + - 'Concepts and APIs': + - 'Gateways': + - 'Defining and Distributing Multicluster Gateways with OCM': multicluster-gateway-controller/docs/gateways/define-and-place-a-gateway.md + - 'Gateway Deletion': multicluster-gateway-controller/docs/gateways/gateway-deletion.md + - 'DNSPolicy': + - 'DNSPolicy Quickstart': multicluster-gateway-controller/docs/dnspolicy/dnspolicy-quickstart.md + - 'DNSPolicy Reference': multicluster-gateway-controller/docs/dnspolicy/dns-policy.md + - 'DNS Health Checks': multicluster-gateway-controller/docs/dnspolicy/dns-health-checks.md + - 'DNS Providers': multicluster-gateway-controller/docs/dnspolicy/dns-provider.md + - 'ManagedZone Reference': multicluster-gateway-controller/docs/dnspolicy/managed-zone.md + - 'TLSPolicy': + - 'TLSPpolicy Reference': multicluster-gateway-controller/docs/tlspolicy/tls-policy.md + - 'AuthPolicy': + - 'AuthPolicy RFC': architecture/rfcs/0001-rlp-v2.md + - 'RateLimitPolicy': - 'RateLimitPolicy Overview': kuadrant-operator/doc/rate-limiting.md - 'RateLimitPolicy (v1beta2)': kuadrant-operator/doc/ratelimitpolicy-reference.md - - "Developer's Guide": kuadrant-operator/doc/development.md - - 'Authorino': - - 'Overview': authorino/README.md - - 'Authorino Operator': authorino-operator/README.md - - 'Getting Started': authorino/docs/getting-started.md - - 'Architecture': authorino/docs/architecture.md - - 'How-to': + - 'How-to Guides': + - 'Multicluster Gateway Controller': + - 'Multicluster Gateways Walkthrough': multicluster-gateway-controller/docs/how-to/multicluster-gateways-walkthrough.md + - 'Metrics Federation': multicluster-gateway-controller/docs/how-to/metrics-federation.md + - 'Metrics Walkthrough': multicluster-gateway-controller/docs/how-to/metrics-walkthrough.md + - 'Authorino': - 'Hello World': authorino/docs/user-guides/hello-world.md - 'Authentication with Kubernetes tokens (TokenReview API)': authorino/docs/user-guides/kubernetes-tokenreview.md - 'Authentication with API keys': authorino/docs/user-guides/api-key-authentication.md @@ -114,49 +123,46 @@ nav: - 'Reducing the operational space: sharding, noise and multi-tenancy': authorino/docs/user-guides/sharding.md - 'Caching': authorino/docs/user-guides/caching.md - 'Observability': authorino/docs/user-guides/observability.md - - 'Reference': authorino/docs/features.md - - "Developer's Guide": authorino/docs/contributing.md - - 'Limitador': - - 'Overview': limitador/README.md - - 'How it works': limitador/doc/how-it-works.md - - 'Topologies': limitador/doc/topologies.md - - 'Server': - - 'Overview': limitador/limitador-server/README.md - - 'Sandbox': limitador/limitador-server/docs/sandbox.md - - 'Crate': limitador/limitador/README.md - - 'Limitador Operator': - - 'Overview': limitador-operator/README.md - - 'Storage': limitador-operator/doc/storage.md - - 'Rate limit headers': limitador-operator/doc/rate-limit-headers.md - - "Developer's Guide": limitador-operator/doc/development.md - - limitador-operator/doc/logging.md - - 'Multicluster Gateway Controller': - - 'Overview': multicluster-gateway-controller/README.md - - 'Getting Started': multicluster-gateway-controller/docs/getting-started.md - - 'Installation Guides': - - 'Control Plane installation with Existing OCM': multicluster-gateway-controller/docs/installation/control-plane-installation.md - - 'Service Protection installation with Existing OCM': multicluster-gateway-controller/docs/installation/service-protection-installation.md - - 'Concepts and APIs': - - 'Gateways': - - 'Defining and Distributing Multicluster Gateways with OCM': multicluster-gateway-controller/docs/gateways/define-and-place-a-gateway.md - - 'Gateway Deletion': multicluster-gateway-controller/docs/gateways/gateway-deletion.md - - 'DNSPolicy': - - 'DNSPolicy Quickstart': multicluster-gateway-controller/docs/dnspolicy/dnspolicy-quickstart.md - - 'DNSPolicy Reference': multicluster-gateway-controller/docs/dnspolicy/dns-policy.md - - 'DNS Health Checks': multicluster-gateway-controller/docs/dnspolicy/dns-health-checks.md - - 'DNS Providers': multicluster-gateway-controller/docs/dnspolicy/dns-provider.md - - 'ManagedZone Reference': multicluster-gateway-controller/docs/dnspolicy/managed-zone.md - - 'TLSPolicy': - - 'TLSPpolicy Reference': multicluster-gateway-controller/docs/tlspolicy/tls-policy.md - - 'How-to Guides': - - 'Multicluster Gateways Walkthrough': multicluster-gateway-controller/docs/how-to/multicluster-gateways-walkthrough.md - - 'Metrics Federation': multicluster-gateway-controller/docs/how-to/metrics-federation.md - - 'Metrics Walkthrough': multicluster-gateway-controller/docs/how-to/metrics-walkthrough.md - - 'Contribution': - - 'Debugging with VSCode': multicluster-gateway-controller/docs/contribution/vscode-debugging.md - - 'Experimental': - - 'Kuadrant and Skupper Gateway Resiliency': multicluster-gateway-controller/docs/experimental/skupper-poc-2-gateways-resiliency-walkthrough.md - - 'Kuadrant and Submariner Gateway Resiliency': multicluster-gateway-controller/docs/experimental/submariner-poc-2-gateways-resiliency-walkthrough.md - - 'Proposals': - - 'Proposal: Multiple DNS Provider Support': multicluster-gateway-controller/docs/proposals/multiple-dns-provider-support.md - - 'Proposal: Aggregation of Status Conditions': multicluster-gateway-controller/docs/proposals/status-aggregation.md + - 'Experimental': + - 'Kuadrant and Skupper Gateway Resiliency': multicluster-gateway-controller/docs/experimental/skupper-poc-2-gateways-resiliency-walkthrough.md + - 'Kuadrant and Submariner Gateway Resiliency': multicluster-gateway-controller/docs/experimental/submariner-poc-2-gateways-resiliency-walkthrough.md + - 'Proposals': + - 'Multicluster Gateway Controller': + - 'Proposal: Multiple DNS Provider Support': multicluster-gateway-controller/docs/proposals/multiple-dns-provider-support.md + - 'Proposal: Aggregation of Status Conditions': multicluster-gateway-controller/docs/proposals/status-aggregation.md + - 'Components': + - 'Kuadrant Operator': + - 'Overview': kuadrant-operator/README.md + - 'How-to': + - kuadrant-operator/doc/user-guides/simple-rl-for-app-developers.md + - kuadrant-operator/doc/user-guides/gateway-rl-for-cluster-operators.md + - kuadrant-operator/doc/user-guides/authenticated-rl-for-app-developers.md + - kuadrant-operator/doc/user-guides/authenticated-rl-with-jwt-and-k8s-authnz.md + - kuadrant-operator/doc/logging.md + - "Developer's Guide": kuadrant-operator/doc/development.md + - 'Authorino': + - 'Overview': authorino/README.md + - 'Authorino Operator': authorino-operator/README.md + - 'Getting Started': authorino/docs/getting-started.md + - 'Architecture': authorino/docs/architecture.md + - 'Reference': authorino/docs/features.md + - "Developer's Guide": authorino/docs/contributing.md + - 'Limitador': + - 'Overview': limitador/README.md + - 'How it works': limitador/doc/how-it-works.md + - 'Topologies': limitador/doc/topologies.md + - 'Server': + - 'Overview': limitador/limitador-server/README.md + - 'Sandbox': limitador/limitador-server/docs/sandbox.md + - 'Crate': limitador/limitador/README.md + - 'Limitador Operator': + - 'Overview': limitador-operator/README.md + - 'Storage': limitador-operator/doc/storage.md + - 'Rate limit headers': limitador-operator/doc/rate-limit-headers.md + - "Developer's Guide": limitador-operator/doc/development.md + - limitador-operator/doc/logging.md + - 'Multicluster Gateway Controller': + - 'Overview': multicluster-gateway-controller/README.md + - 'Contribution': + - 'Debugging with VSCode': multicluster-gateway-controller/docs/contribution/vscode-debugging.md + From dc69b180a9eddc8bbe24fb13de71884e84756b69 Mon Sep 17 00:00:00 2001 From: Jason Madigan Date: Tue, 12 Sep 2023 10:25:27 +0100 Subject: [PATCH 2/2] add a note on deployment --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e6a7fc4a..822d2cc3 100644 --- a/README.md +++ b/README.md @@ -18,4 +18,6 @@ And dependencies Outputs static content to `site`. ## Deploying -This is deployed via GitHub Pages. +This is deployed via GitHub Pages, on merge to `main`. + +If you need to re-trigger a deployment from main for any reason, manually run `Actions`>`ci` for the latest workflow run. This will build a docs bundle, and then trigger the `pages-build-deployment` action afterwards to push changes to the `gh-pages` branch. \ No newline at end of file