From 4e08b7db578df22b0e86c22f207bd03338bf3da4 Mon Sep 17 00:00:00 2001 From: Charly Molter Date: Fri, 30 Jun 2023 13:34:55 +0200 Subject: [PATCH 1/4] feat: add new reference docs Signed-off-by: Charly Molter --- app/_data/docs_nav_kuma_dev.yml | 80 +------------ app/_src/policies/circuit-breaker.md | 4 + app/_src/policies/external-services.md | 4 + app/_src/policies/fault-injection.md | 4 + app/_src/policies/health-check.md | 4 + app/_src/policies/mesh-gateway-route.md | 4 + app/_src/policies/mesh-gateway.md | 4 + app/_src/policies/meshaccesslog.md | 2 +- app/_src/policies/meshcircuitbreaker.md | 2 +- app/_src/policies/meshfaultinjection.md | 2 +- app/_src/policies/meshgatewayinstance.md | 4 +- app/_src/policies/meshhealthcheck.md | 2 +- app/_src/policies/meshhttproute.md | 2 +- .../policies/meshloadbalancingstrategy.md | 2 +- app/_src/policies/meshproxypatch.md | 2 +- app/_src/policies/meshratelimit.md | 2 +- app/_src/policies/meshretry.md | 2 +- app/_src/policies/meshtcproute.md | 2 +- app/_src/policies/meshtimeout.md | 2 +- app/_src/policies/meshtrace.md | 2 +- app/_src/policies/meshtrafficpermission.md | 2 +- app/_src/policies/rate-limit.md | 4 + app/_src/policies/retry.md | 4 + app/_src/policies/timeout.md | 6 +- app/_src/policies/traffic-log.md | 3 + app/_src/policies/traffic-permissions.md | 4 + app/_src/policies/traffic-route.md | 4 + app/_src/policies/traffic-trace.md | 4 + app/_src/policies/virtual-outbound.md | 4 + .../production/dp-config/dpp-on-kubernetes.md | 6 +- .../production/dp-config/dpp-on-universal.md | 4 + app/_src/reference/kuma-cp.md | 13 +++ app/_src/reference/proxy-template.md | 4 + .../lib/jekyll/kuma-plugins.rb | 3 +- .../liquid/tags/embedversioned.rb | 25 ++++ .../kuma-plugins/liquid/tags/jsonschema.rb | 108 ++++++++++++++++++ .../kuma-plugins/liquid/tags/policyschema.rb | 47 -------- 37 files changed, 234 insertions(+), 143 deletions(-) create mode 100644 app/_src/reference/kuma-cp.md create mode 100644 jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embedversioned.rb create mode 100644 jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb delete mode 100644 jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/policyschema.rb diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index baa4f86f3..2c394196d 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -570,86 +570,10 @@ items: url: /reference/kubernetes-annotations/ - text: Kuma data collection url: /reference/data-collection/ - - # Auto-generated - text: Control plane configuration reference - url: /generated/kuma-cp - generate: false + - text: Control plane configuration reference + url: /reference/kuma-cp - text: Envoy proxy template url: /reference/proxy-template/ - - # Auto-generated - title: Resources - group: true - items: - - text: Mesh - url: /generated/resources/other_mesh/ - generate: false - - text: CircuitBreaker - url: /generated/resources/policy_circuit-breaker/ - generate: false - - text: ExternalService - url: /generated/resources/policy_external-service/ - generate: false - - text: FaultInjection - url: /generated/resources/policy_fault-injection/ - generate: false - - text: HealthCheck - url: /generated/resources/policy_health-check/ - generate: false - - text: MeshGateway - url: /generated/resources/policy_meshgateway/ - generate: false - - text: MeshGatewayRoute - url: /generated/resources/policy_meshgatewayroute/ - generate: false - - text: ProxyTemplate - url: /generated/resources/policy_proxy-template/ - generate: false - - text: RateLimit - url: /generated/resources/policy_rate-limit/ - generate: false - - text: Retry - url: /generated/resources/policy_retry/ - generate: false - - text: Timeout - url: /generated/resources/policy_timeout/ - generate: false - - text: TrafficLog - url: /generated/resources/policy_traffic-log/ - generate: false - - text: TrafficPermission - url: /generated/resources/policy_traffic-permissions/ - generate: false - - text: TrafficRoute - url: /generated/resources/policy_traffic-route/ - generate: false - - text: TrafficTrace - url: /generated/resources/policy_traffic-trace/ - generate: false - - text: VirtualOutbound - url: /generated/resources/policy_virtual-outbound/ - generate: false - - text: Dataplane - url: /generated/resources/proxy_dataplane/ - generate: false - - text: ZoneEgress - url: /generated/resources/proxy_zoneegress/ - generate: false - - text: ZoneIngress - url: /generated/resources/proxy_zoneingress/ - generate: false - - # Auto-generated - title: Commands - group: true - items: - - text: kuma-cp - url: /generated/cmd/kuma-cp/kuma-cp/ - generate: false - - text: kuma-dp - url: /generated/cmd/kuma-dp/kuma-dp/ - generate: false - - text: kumactl - url: /generated/cmd/kumactl/kumactl/ - generate: false - title: Community group: true items: diff --git a/app/_src/policies/circuit-breaker.md b/app/_src/policies/circuit-breaker.md index feac5f2be..cdf707e63 100644 --- a/app/_src/policies/circuit-breaker.md +++ b/app/_src/policies/circuit-breaker.md @@ -248,3 +248,7 @@ Circuit Breaker policies are supported on the builtin gateway like any other dat When [passthrough mode](/docs/{{ page.version }}/networking/non-mesh-traffic#outgoing) is activated any non-mesh traffic is passing Envoy without applying the CircuitBreaker policies. Read more about [Non-mesh traffic](/docs/{{ page.version }}/networking/non-mesh-traffic#circuit-breaker). + +## All policy options + +{% json_schema CircuitBreaker type=proto %} diff --git a/app/_src/policies/external-services.md b/app/_src/policies/external-services.md index 18fee268a..464a349ab 100644 --- a/app/_src/policies/external-services.md +++ b/app/_src/policies/external-services.md @@ -244,3 +244,7 @@ In this example, when all the conditions mentioned above are fulfilled if the se Note that mesh Dataplanes can be configured with the same `kuma.io/service` tag as an external service resource. In this scenario, {{site.mesh_product_name}} Gateway will prefer the ExternalService and not route any traffic to the Dataplanes. Note that before gateway becomes generally available this behaviour will change to be the same as for any other dataplanes. + +## All options + +{% json_schema ExternalService type=proto %} diff --git a/app/_src/policies/fault-injection.md b/app/_src/policies/fault-injection.md index c579848bf..57cf103a6 100644 --- a/app/_src/policies/fault-injection.md +++ b/app/_src/policies/fault-injection.md @@ -109,3 +109,7 @@ ResponseBandwidth defines a configuration to limit the speed of responding to th `FaultInjection` is an [Inbound Connection Policy](/docs/{{ page.version }}/policies/how-kuma-chooses-the-right-policy-to-apply#outbound-connection-policy). You can use all the tags in both `sources` and `destinations` sections. + +## All options + +{% json_schema FaultInjection type=proto %} diff --git a/app/_src/policies/health-check.md b/app/_src/policies/health-check.md index 1ca75781c..50af52069 100644 --- a/app/_src/policies/health-check.md +++ b/app/_src/policies/health-check.md @@ -152,3 +152,7 @@ HTTP health checks are executed using HTTP 2 `HealthCheck` is an [Outbound Connection Policy](/docs/{{ page.version }}/policies/how-kuma-chooses-the-right-policy-to-apply/#outbound-connection-policy). The only supported value for `destinations.match` is `kuma.io/service`. + +## All options + +{% json_schema HealthCheck type=proto %} diff --git a/app/_src/policies/mesh-gateway-route.md b/app/_src/policies/mesh-gateway-route.md index 206b0bba1..9bf4c79ff 100644 --- a/app/_src/policies/mesh-gateway-route.md +++ b/app/_src/policies/mesh-gateway-route.md @@ -105,3 +105,7 @@ For example, the following filters match `/prefix`, trim it from the path and se ## Reference The reference doc contains all options on [`MeshGatewayRoute`](/docs/{{ page.version }}/generated/resources/policy_meshgatewayroute). + +## All options + +{% json_schema MeshGatewayRoute type=proto %} diff --git a/app/_src/policies/mesh-gateway.md b/app/_src/policies/mesh-gateway.md index 2a43a22e6..bac3bff11 100644 --- a/app/_src/policies/mesh-gateway.md +++ b/app/_src/policies/mesh-gateway.md @@ -232,3 +232,7 @@ EOF ``` {% endtab %} {% endtabs %} + +## All options + +{% json_schema MeshGateway type=proto %} diff --git a/app/_src/policies/meshaccesslog.md b/app/_src/policies/meshaccesslog.md index d26f9fb55..70c9200bd 100644 --- a/app/_src/policies/meshaccesslog.md +++ b/app/_src/policies/meshaccesslog.md @@ -836,4 +836,4 @@ You can select a built-in gateway using the `kuma.io/service` value. A current l ## All policy options -{% policy_schema MeshAccessLog %} +{% json_schema MeshAccessLogs %} diff --git a/app/_src/policies/meshcircuitbreaker.md b/app/_src/policies/meshcircuitbreaker.md index 1ad95eb0f..d65c04c8a 100644 --- a/app/_src/policies/meshcircuitbreaker.md +++ b/app/_src/policies/meshcircuitbreaker.md @@ -506,4 +506,4 @@ spec: ## All policy options -{% policy_schema MeshCircuitBreaker %} +{% json_schema MeshCircuitBreakers %} diff --git a/app/_src/policies/meshfaultinjection.md b/app/_src/policies/meshfaultinjection.md index 347a1266a..f27ede6be 100644 --- a/app/_src/policies/meshfaultinjection.md +++ b/app/_src/policies/meshfaultinjection.md @@ -264,4 +264,4 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](../. ## All policy options -{% policy_schema MeshFaultInjection %} +{% json_schema MeshFaultInjections %} diff --git a/app/_src/policies/meshgatewayinstance.md b/app/_src/policies/meshgatewayinstance.md index e73624de6..4e66ea9a5 100644 --- a/app/_src/policies/meshgatewayinstance.md +++ b/app/_src/policies/meshgatewayinstance.md @@ -115,6 +115,6 @@ spec: {% endif_version %} -## `.spec` schema +## schema -{% policy_schema MeshGatewayInstance %} +{% json_schema kuma.io_meshgatewayinstances type=crd %} diff --git a/app/_src/policies/meshhealthcheck.md b/app/_src/policies/meshhealthcheck.md index 70fb790ae..b1839e679 100644 --- a/app/_src/policies/meshhealthcheck.md +++ b/app/_src/policies/meshhealthcheck.md @@ -296,4 +296,4 @@ HTTP health checks are executed using HTTP2 ## All policy options -{% policy_schema MeshHealthCheck %} +{% json_schema MeshHealthChecks %} diff --git a/app/_src/policies/meshhttproute.md b/app/_src/policies/meshhttproute.md index c8f9dda6a..21168e461 100644 --- a/app/_src/policies/meshhttproute.md +++ b/app/_src/policies/meshhttproute.md @@ -481,4 +481,4 @@ rules: ## All policy options -{% policy_schema MeshHTTPRoute %} +{% json_schema MeshHttpRoutes %} diff --git a/app/_src/policies/meshloadbalancingstrategy.md b/app/_src/policies/meshloadbalancingstrategy.md index 2c17f3f90..98589f4fb 100644 --- a/app/_src/policies/meshloadbalancingstrategy.md +++ b/app/_src/policies/meshloadbalancingstrategy.md @@ -239,4 +239,4 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](../. ## All policy options -{% policy_schema MeshLoadBalancingStrategy %} +{% json_schema MeshLoadBalancingStrategies %} diff --git a/app/_src/policies/meshproxypatch.md b/app/_src/policies/meshproxypatch.md index 87d132c2c..b0b945a51 100644 --- a/app/_src/policies/meshproxypatch.md +++ b/app/_src/policies/meshproxypatch.md @@ -1582,4 +1582,4 @@ spec: ## All policy options -{% policy_schema MeshProxyPatch %} +{% json_schema MeshProxyPatches %} diff --git a/app/_src/policies/meshratelimit.md b/app/_src/policies/meshratelimit.md index 871a37894..ac0f72df5 100644 --- a/app/_src/policies/meshratelimit.md +++ b/app/_src/policies/meshratelimit.md @@ -185,4 +185,4 @@ We will apply the configuration with `kumactl apply -f [..]` or via the [HTTP AP ## All policy options -{% policy_schema MeshRateLimit %} +{% json_schema MeshRateLimits %} diff --git a/app/_src/policies/meshretry.md b/app/_src/policies/meshretry.md index bc3c486e8..2fd296f79 100644 --- a/app/_src/policies/meshretry.md +++ b/app/_src/policies/meshretry.md @@ -327,4 +327,4 @@ Apply the configuration with `kumactl apply -f [..]` or with the [HTTP API](../. ## All policy options -{% policy_schema MeshRetry %} +{% json_schema MeshRetries %} diff --git a/app/_src/policies/meshtcproute.md b/app/_src/policies/meshtcproute.md index 5d26c31a6..2627b3072 100644 --- a/app/_src/policies/meshtcproute.md +++ b/app/_src/policies/meshtcproute.md @@ -249,4 +249,4 @@ Depending on the `backend`'s protocol: ## All policy configuration settings -{% policy_schema MeshTCPRoute %} +{% json_schema MeshTCPRoutes %} diff --git a/app/_src/policies/meshtimeout.md b/app/_src/policies/meshtimeout.md index 44b73c84c..0f7890921 100644 --- a/app/_src/policies/meshtimeout.md +++ b/app/_src/policies/meshtimeout.md @@ -270,4 +270,4 @@ is [a known bug](https://github.com/kumahq/kuma/issues/5850) and is fixed in the ## All policy options -{% policy_schema MeshTimeout %} +{% json_schema MeshTimeouts %} diff --git a/app/_src/policies/meshtrace.md b/app/_src/policies/meshtrace.md index 413f2a307..2ad443d3c 100644 --- a/app/_src/policies/meshtrace.md +++ b/app/_src/policies/meshtrace.md @@ -960,4 +960,4 @@ spec: ## All policy options -{% policy_schema MeshTrace %} +{% json_schema MeshTraces %} diff --git a/app/_src/policies/meshtrafficpermission.md b/app/_src/policies/meshtrafficpermission.md index 243e23338..44a3152cb 100644 --- a/app/_src/policies/meshtrafficpermission.md +++ b/app/_src/policies/meshtrafficpermission.md @@ -280,4 +280,4 @@ This is because the rule with `Deny` is later in the `from` array than any `Allo ## All policy options -{% policy_schema MeshTrafficPermission %} +{% json_schema MeshTrafficPermissions %} diff --git a/app/_src/policies/rate-limit.md b/app/_src/policies/rate-limit.md index 8a3473cc2..bf6837e12 100644 --- a/app/_src/policies/rate-limit.md +++ b/app/_src/policies/rate-limit.md @@ -167,3 +167,7 @@ When applied to an [ExternalService](/docs/{{ page.version }}/policies/external- {{site.mesh_product_name}} Gateway supports the `RateLimit` connection policy. Rate limits are configured on each Envoy route by selecting the best Rate Limit policy that matches the source and destination. + +## All options + +{% json_schema RateLimit type=proto %} diff --git a/app/_src/policies/retry.md b/app/_src/policies/retry.md index 7ef262ca2..c3cd746d5 100644 --- a/app/_src/policies/retry.md +++ b/app/_src/policies/retry.md @@ -242,3 +242,7 @@ The only supported value for `destinations.match` is `kuma.io/service`. ## Builtin Gateway support Retries can be configured on each route by matching the `Retry` connection policy to the backend destination tags. + +## All options + +{% json_schema Retry type=proto %} diff --git a/app/_src/policies/timeout.md b/app/_src/policies/timeout.md index b52d7bb1f..7c53e7221 100644 --- a/app/_src/policies/timeout.md +++ b/app/_src/policies/timeout.md @@ -218,4 +218,8 @@ since it has a high likelihood of yielding connection leaks. When [passthrough mode](/docs/{{ page.version }}/networking/non-mesh-traffic#outgoing) is activated any non-mesh traffic is passing Envoy without applying the Timeout policies. -Read more about [Non-mesh traffic](/docs/{{ page.version }}/networking/non-mesh-traffic#timeouts). \ No newline at end of file +Read more about [Non-mesh traffic](/docs/{{ page.version }}/networking/non-mesh-traffic#timeouts). + +## All options + +{% json_schema Timeout type=proto %} diff --git a/app/_src/policies/traffic-log.md b/app/_src/policies/traffic-log.md index b4c351e95..dbe8ac463 100644 --- a/app/_src/policies/traffic-log.md +++ b/app/_src/policies/traffic-log.md @@ -240,3 +240,6 @@ If you need an access log with entries in `JSON` format, you have to provide a t "bytes_sent": "%BYTES_SENT%" } ``` +## All policy options + +{% json_schema TrafficLog type=proto %} diff --git a/app/_src/policies/traffic-permissions.md b/app/_src/policies/traffic-permissions.md index f8f799391..1140be07c 100644 --- a/app/_src/policies/traffic-permissions.md +++ b/app/_src/policies/traffic-permissions.md @@ -148,3 +148,7 @@ destinations: {% endtabs %} Remember, the `ExternalService` follows [the same rules](/docs/{{ page.version }}/policies/how-kuma-chooses-the-right-policy-to-apply) for matching policies as any other service in the mesh -- {{site.mesh_product_name}} selects the most specific `TrafficPermission` for every `ExternalService`. + +## All options + +{% json_schema TrafficPermission type=proto %} diff --git a/app/_src/policies/traffic-route.md b/app/_src/policies/traffic-route.md index 5ade3ebb6..b0b62a2b6 100644 --- a/app/_src/policies/traffic-route.md +++ b/app/_src/policies/traffic-route.md @@ -597,3 +597,7 @@ There are different load balancing algorithms that can be used to determine how loadBalancer: maglev: {} ``` + +## All options + +{% json_schema TrafficRoute type=proto %} diff --git a/app/_src/policies/traffic-trace.md b/app/_src/policies/traffic-trace.md index 444135b9b..c099e670a 100644 --- a/app/_src/policies/traffic-trace.md +++ b/app/_src/policies/traffic-trace.md @@ -179,3 +179,7 @@ You can also add tags to apply the `TrafficTrace` resource only a subset of data While most commonly we want all the traces to be sent to the same tracing backend, we can optionally create multiple tracing backends in a `Mesh` resource and store traces for different paths of our service traffic in different backends by leveraging {{site.mesh_product_name}} tags. This is especially useful when we want traces to never leave a world region, or a cloud, for example. {% endtip %} + +## All options + +{% json_schema TrafficTrace type=proto %} diff --git a/app/_src/policies/virtual-outbound.md b/app/_src/policies/virtual-outbound.md index c1fb075f6..39dc5ba44 100644 --- a/app/_src/policies/virtual-outbound.md +++ b/app/_src/policies/virtual-outbound.md @@ -273,3 +273,7 @@ conf: {% endraw %} {% endtab %} {% endtabs %} + +## All options + +{% json_schema VirtualOutbound type=proto %} diff --git a/app/_src/production/dp-config/dpp-on-kubernetes.md b/app/_src/production/dp-config/dpp-on-kubernetes.md index d5ee860fd..8e98a40c4 100644 --- a/app/_src/production/dp-config/dpp-on-kubernetes.md +++ b/app/_src/production/dp-config/dpp-on-kubernetes.md @@ -403,7 +403,7 @@ but your workload will be annotated with its own list of patches (i.e. `["pod-patch-1", "pod-patch-2]`) only the latter will be applied. {% endtip %} -#### Example +To install a CP with env vars you can do: ```shell kumactl install control-plane --env-var "KUMA_RUNTIME_KUBERNETES_INJECTOR_CONTAINER_PATCHES=patch1,patch2" @@ -418,6 +418,10 @@ a sane configuration. If a workload refers to a `ContainerPatch` which does not exist, the injection will explicitly fail and log the failure. +### Schema + +{% json_schema kuma.io_containerpatches type=crd %} + ## Direct access to services By default, on Kubernetes data plane proxies communicate with each other by leveraging the `ClusterIP` address of the `Service` resources. Also by default, any request made to another service is automatically load balanced client-side by the data plane proxy that originates the request (they are load balanced by the local Envoy proxy sidecar proxy). diff --git a/app/_src/production/dp-config/dpp-on-universal.md b/app/_src/production/dp-config/dpp-on-universal.md index 446429b0a..eaf2be170 100644 --- a/app/_src/production/dp-config/dpp-on-universal.md +++ b/app/_src/production/dp-config/dpp-on-universal.md @@ -197,3 +197,7 @@ networking: ``` If the `admin` section is empty or port is equal to zero then the default value for port will be taken from the [{{site.mesh_product_name}} Control Plane configuration](/docs/{{ page.version }}/generated/kuma-cp). + +## Dataplane configuration + +{% json_schema Dataplane type=proto %} diff --git a/app/_src/reference/kuma-cp.md b/app/_src/reference/kuma-cp.md new file mode 100644 index 000000000..74bce3886 --- /dev/null +++ b/app/_src/reference/kuma-cp.md @@ -0,0 +1,13 @@ +--- +title: kuma-cp configuration reference +--- + +## Kuma CP configuration +```yaml +{% embed_versioned kuma-cp.yaml %} +``` + +## Helm values.yaml +```yaml +{% embed_versioned helm-values.yaml %} +``` diff --git a/app/_src/reference/proxy-template.md b/app/_src/reference/proxy-template.md index 8ff20ec24..a59e1b35e 100644 --- a/app/_src/reference/proxy-template.md +++ b/app/_src/reference/proxy-template.md @@ -900,3 +900,7 @@ conf: The Proxy Template policy supports a new `gateway-proxy` configuration name that can be imported. This generates the Envoy resources for a {{site.mesh_product_name}} Gateway proxy. The origin name for matching template modifications is `gateway`. + +## Schema + +{% json_schema ProxyTemplate type=proto %} diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb index 409a7b10b..e89c64ebc 100644 --- a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb +++ b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true require_relative "kuma-plugins/version" -require_relative 'kuma-plugins/liquid/tags/policyschema' +require_relative 'kuma-plugins/liquid/tags/jsonschema' +require_relative 'kuma-plugins/liquid/tags/embedversioned' require_relative 'kuma-plugins/liquid/tags/policyyaml' diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embedversioned.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embedversioned.rb new file mode 100644 index 000000000..c7f601bb6 --- /dev/null +++ b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embedversioned.rb @@ -0,0 +1,25 @@ +module Jekyll + module KumaPlugins + module Liquid + module Tags + class EmbedVersioned < ::Liquid::Tag + def initialize(tag_name, markup, options) + super + @file = @markup.strip + end + + def render(context) + base_path = context.registers[:site].config.fetch('mesh_raw_generated_path', 'app/docs') + release = context.registers[:page]['release'] + path = "#{base_path}/#{release}/generated/raw/#{@file}" + File.read(path) rescue begin + Jekyll.logger.warn("Failed reading raw file", path) + return + end + end + end + end + end + end +end +Liquid::Template.register_tag('embed_versioned', Jekyll::KumaPlugins::Liquid::Tags::EmbedVersioned) diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb new file mode 100644 index 000000000..ce67fcdfe --- /dev/null +++ b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb @@ -0,0 +1,108 @@ +require 'json' +require 'yaml' + +module Jekyll + module KumaPlugins + module Liquid + module Tags + class JsonSchema < ::Liquid::Tag + def initialize(tag_name, markup, options) + super + name, *params_list = @markup.split(' ') + params = {'type' => 'policy'} + params_list.each do |item| + sp = item.split('=') + params[sp[0]] = sp[1] unless sp[1] == '' + end + @type = create_loader(params['type'], name) + end + + def render(context) + release = context.registers[:page]['release'] + base_path = context.registers[:site].config.fetch('mesh_raw_generated_path', 'app/docs') + data = @type.load("#{base_path}/#{release}/generated/raw") + + <<~TIP +
+ + + TIP + end + end + end + end + end +end + +class ProtoReader + def initialize(name) + @name = name + end + def load(base_path) + path = "#{base_path}/protos/#{@name}.json" + file = File.open(path) rescue begin + Jekyll.logger.warn("Failed reading proto", path) + return + end + d = JSON.load(file) + return d + end +end +class CrdReader + def initialize(name) + @name = name + end + def load(base_path) + path = "#{base_path}/crds/#{@name}.yaml" + file = File.open(path) rescue begin + Jekyll.logger.warn("Failed reading crd", path) + return + end + d = YAML.load(file) + return d['spec']['versions'][0]['schema']['openAPIV3Schema'] + end +end +class PolicyReader + def initialize(name) + @name = name + end + def load(base_path) + path = "#{base_path}/crds/kuma.io_#{@name.downcase}.yaml" + file = File.open(path) rescue begin + Jekyll.logger.warn("Failed reading policy", path) + return + end + d = YAML.load(file) + return d['spec']['versions'][0]['schema']['openAPIV3Schema']['properties']['spec'] + end +end +def create_loader(type, name) + case type + when 'proto' + ProtoReader.new(name) + when 'crd' + CrdReader.new(name) + when 'policy' + PolicyReader.new(name) + else + raise "Invalid type: #{type}" + end +end +Liquid::Template.register_tag('json_schema', Jekyll::KumaPlugins::Liquid::Tags::JsonSchema) diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/policyschema.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/policyschema.rb deleted file mode 100644 index e69afbe44..000000000 --- a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/policyschema.rb +++ /dev/null @@ -1,47 +0,0 @@ -module Jekyll - module KumaPlugins - module Liquid - module Tags - class PolicySchema < ::Liquid::Tag - def initialize(tag_name, markup, options) - super - - @markup = markup.strip - end - - def render(context) - release = context.registers[:page]['release'] - - <<~TIP -
- - - TIP - end - end - end - end - end -end - -Liquid::Template.register_tag('policy_schema', Jekyll::KumaPlugins::Liquid::Tags::PolicySchema) From a87cc0b76667831c73f0986eb9bb362bd64985a2 Mon Sep 17 00:00:00 2001 From: Charly Molter Date: Fri, 30 Jun 2023 17:43:40 +0200 Subject: [PATCH 2/4] fix with actual files Signed-off-by: Charly Molter --- app/_data/docs_nav_kuma_2.1.x.yml | 85 +------------------ app/_data/docs_nav_kuma_2.2.x.yml | 83 +----------------- app/_data/docs_nav_kuma_2.3.x.yml | 83 +----------------- app/_data/docs_nav_kuma_dev.yml | 3 +- app/_src/introduction/changelog.md | 5 ++ app/_src/reference/kuma-cp.md | 4 +- .../lib/jekyll/kuma-plugins.rb | 2 +- .../tags/{embedversioned.rb => embed.rb} | 15 +++- .../kuma-plugins/liquid/tags/jsonschema.rb | 2 +- 9 files changed, 31 insertions(+), 251 deletions(-) create mode 100644 app/_src/introduction/changelog.md rename jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/{embedversioned.rb => embed.rb} (54%) diff --git a/app/_data/docs_nav_kuma_2.1.x.yml b/app/_data/docs_nav_kuma_2.1.x.yml index 4817f098e..187f3f365 100644 --- a/app/_data/docs_nav_kuma_2.1.x.yml +++ b/app/_data/docs_nav_kuma_2.1.x.yml @@ -26,9 +26,8 @@ items: src: /production/deployment/ - text: Enterprise url: /introduction/enterprise/ - - text: Changelog - absolute_url: true - url: https://github.com/kumahq/kuma/blob/master/CHANGELOG.md + - text: Release notes + url: /introduction/changelog/ - title: Install group: true items: @@ -810,84 +809,8 @@ items: - text: License url: /reference/license/ src: "/community/license/" - - # Auto-generated - title: Resources - group: true - items: - - text: Mesh - url: /generated/resources/other_mesh/ - generate: false - - text: CircuitBreaker - url: /generated/resources/policy_circuit-breaker/ - generate: false - - text: ExternalService - url: /generated/resources/policy_external-service/ - generate: false - - text: FaultInjection - url: /generated/resources/policy_fault-injection/ - generate: false - - text: HealthCheck - url: /generated/resources/policy_health-check/ - generate: false - - text: MeshGateway - url: /generated/resources/policy_meshgateway/ - generate: false - - text: MeshGatewayRoute - url: /generated/resources/policy_meshgatewayroute/ - generate: false - - text: ProxyTemplate - url: /generated/resources/policy_proxy-template/ - generate: false - - text: RateLimit - url: /generated/resources/policy_rate-limit/ - generate: false - - text: Retry - url: /generated/resources/policy_retry/ - generate: false - - text: Timeout - url: /generated/resources/policy_timeout/ - generate: false - - text: TrafficLog - url: /generated/resources/policy_traffic-log/ - generate: false - - text: TrafficPermission - url: /generated/resources/policy_traffic-permissions/ - generate: false - - text: TrafficRoute - url: /generated/resources/policy_traffic-route/ - generate: false - - text: TrafficTrace - url: /generated/resources/policy_traffic-trace/ - generate: false - - text: VirtualOutbound - url: /generated/resources/policy_virtual-outbound/ - generate: false - - text: Dataplane - url: /generated/resources/proxy_dataplane/ - generate: false - - text: ZoneEgress - url: /generated/resources/proxy_zoneegress/ - generate: false - - text: ZoneIngress - url: /generated/resources/proxy_zoneingress/ - generate: false - - # Auto-generated - title: Commands - group: true - items: - - text: kuma-cp - url: /generated/cmd/kuma-cp/kuma-cp/ - generate: false - - text: kuma-dp - url: /generated/cmd/kuma-dp/kuma-dp/ - generate: false - - text: kumactl - url: /generated/cmd/kumactl/kumactl/ - generate: false - - # Auto-generated - text: Kuma-cp configuration reference - url: /generated/kuma-cp - generate: false + - text: Kuma-cp configuration reference + url: /reference/kuma-cp - title: Contribute group: true items: diff --git a/app/_data/docs_nav_kuma_2.2.x.yml b/app/_data/docs_nav_kuma_2.2.x.yml index c7741fb5f..e38bb48b9 100644 --- a/app/_data/docs_nav_kuma_2.2.x.yml +++ b/app/_data/docs_nav_kuma_2.2.x.yml @@ -24,8 +24,7 @@ items: - text: Kuma requirements url: /introduction/kuma-requirements/ - text: Release notes - absolute_url: true - url: https://github.com/kumahq/kuma/blob/master/CHANGELOG.md + url: /introduction/changelog/ - title: Kuma in Production group: true items: @@ -559,86 +558,10 @@ items: url: /reference/kubernetes-annotations/ - text: Kuma data collection url: /reference/data-collection/ - - # Auto-generated - text: Control plane configuration reference - url: /generated/kuma-cp - generate: false + - text: Control plane configuration reference + url: /reference/kuma-cp/ - text: Envoy proxy template url: /reference/proxy-template/ - - # Auto-generated - title: Resources - group: true - items: - - text: Mesh - url: /generated/resources/other_mesh/ - generate: false - - text: CircuitBreaker - url: /generated/resources/policy_circuit-breaker/ - generate: false - - text: ExternalService - url: /generated/resources/policy_external-service/ - generate: false - - text: FaultInjection - url: /generated/resources/policy_fault-injection/ - generate: false - - text: HealthCheck - url: /generated/resources/policy_health-check/ - generate: false - - text: MeshGateway - url: /generated/resources/policy_meshgateway/ - generate: false - - text: MeshGatewayRoute - url: /generated/resources/policy_meshgatewayroute/ - generate: false - - text: ProxyTemplate - url: /generated/resources/policy_proxy-template/ - generate: false - - text: RateLimit - url: /generated/resources/policy_rate-limit/ - generate: false - - text: Retry - url: /generated/resources/policy_retry/ - generate: false - - text: Timeout - url: /generated/resources/policy_timeout/ - generate: false - - text: TrafficLog - url: /generated/resources/policy_traffic-log/ - generate: false - - text: TrafficPermission - url: /generated/resources/policy_traffic-permissions/ - generate: false - - text: TrafficRoute - url: /generated/resources/policy_traffic-route/ - generate: false - - text: TrafficTrace - url: /generated/resources/policy_traffic-trace/ - generate: false - - text: VirtualOutbound - url: /generated/resources/policy_virtual-outbound/ - generate: false - - text: Dataplane - url: /generated/resources/proxy_dataplane/ - generate: false - - text: ZoneEgress - url: /generated/resources/proxy_zoneegress/ - generate: false - - text: ZoneIngress - url: /generated/resources/proxy_zoneingress/ - generate: false - - # Auto-generated - title: Commands - group: true - items: - - text: kuma-cp - url: /generated/cmd/kuma-cp/kuma-cp/ - generate: false - - text: kuma-dp - url: /generated/cmd/kuma-dp/kuma-dp/ - generate: false - - text: kumactl - url: /generated/cmd/kumactl/kumactl/ - generate: false - title: Community group: true items: diff --git a/app/_data/docs_nav_kuma_2.3.x.yml b/app/_data/docs_nav_kuma_2.3.x.yml index baa4f86f3..cc91a542a 100644 --- a/app/_data/docs_nav_kuma_2.3.x.yml +++ b/app/_data/docs_nav_kuma_2.3.x.yml @@ -22,8 +22,7 @@ items: - text: Kuma requirements url: /introduction/kuma-requirements/ - text: Release notes - absolute_url: true - url: https://github.com/kumahq/kuma/blob/master/CHANGELOG.md + url: /introduction/changelog/ - title: Kuma in Production group: true items: @@ -570,86 +569,10 @@ items: url: /reference/kubernetes-annotations/ - text: Kuma data collection url: /reference/data-collection/ - - # Auto-generated - text: Control plane configuration reference - url: /generated/kuma-cp - generate: false + - text: Control plane configuration reference + url: /reference/kuma-cp/ - text: Envoy proxy template url: /reference/proxy-template/ - - # Auto-generated - title: Resources - group: true - items: - - text: Mesh - url: /generated/resources/other_mesh/ - generate: false - - text: CircuitBreaker - url: /generated/resources/policy_circuit-breaker/ - generate: false - - text: ExternalService - url: /generated/resources/policy_external-service/ - generate: false - - text: FaultInjection - url: /generated/resources/policy_fault-injection/ - generate: false - - text: HealthCheck - url: /generated/resources/policy_health-check/ - generate: false - - text: MeshGateway - url: /generated/resources/policy_meshgateway/ - generate: false - - text: MeshGatewayRoute - url: /generated/resources/policy_meshgatewayroute/ - generate: false - - text: ProxyTemplate - url: /generated/resources/policy_proxy-template/ - generate: false - - text: RateLimit - url: /generated/resources/policy_rate-limit/ - generate: false - - text: Retry - url: /generated/resources/policy_retry/ - generate: false - - text: Timeout - url: /generated/resources/policy_timeout/ - generate: false - - text: TrafficLog - url: /generated/resources/policy_traffic-log/ - generate: false - - text: TrafficPermission - url: /generated/resources/policy_traffic-permissions/ - generate: false - - text: TrafficRoute - url: /generated/resources/policy_traffic-route/ - generate: false - - text: TrafficTrace - url: /generated/resources/policy_traffic-trace/ - generate: false - - text: VirtualOutbound - url: /generated/resources/policy_virtual-outbound/ - generate: false - - text: Dataplane - url: /generated/resources/proxy_dataplane/ - generate: false - - text: ZoneEgress - url: /generated/resources/proxy_zoneegress/ - generate: false - - text: ZoneIngress - url: /generated/resources/proxy_zoneingress/ - generate: false - - # Auto-generated - title: Commands - group: true - items: - - text: kuma-cp - url: /generated/cmd/kuma-cp/kuma-cp/ - generate: false - - text: kuma-dp - url: /generated/cmd/kuma-dp/kuma-dp/ - generate: false - - text: kumactl - url: /generated/cmd/kumactl/kumactl/ - generate: false - title: Community group: true items: diff --git a/app/_data/docs_nav_kuma_dev.yml b/app/_data/docs_nav_kuma_dev.yml index 2c394196d..34721f7ed 100644 --- a/app/_data/docs_nav_kuma_dev.yml +++ b/app/_data/docs_nav_kuma_dev.yml @@ -22,8 +22,7 @@ items: - text: Kuma requirements url: /introduction/kuma-requirements/ - text: Release notes - absolute_url: true - url: https://github.com/kumahq/kuma/blob/master/CHANGELOG.md + url: /introduction/changelog/ - title: Kuma in Production group: true items: diff --git a/app/_src/introduction/changelog.md b/app/_src/introduction/changelog.md new file mode 100644 index 000000000..95945b795 --- /dev/null +++ b/app/_src/introduction/changelog.md @@ -0,0 +1,5 @@ +--- +title: Release notes +--- + +{% embed CHANGELOG.md %} diff --git a/app/_src/reference/kuma-cp.md b/app/_src/reference/kuma-cp.md index 74bce3886..010139a96 100644 --- a/app/_src/reference/kuma-cp.md +++ b/app/_src/reference/kuma-cp.md @@ -4,10 +4,10 @@ title: kuma-cp configuration reference ## Kuma CP configuration ```yaml -{% embed_versioned kuma-cp.yaml %} +{% embed kuma-cp.yaml versioned %} ``` ## Helm values.yaml ```yaml -{% embed_versioned helm-values.yaml %} +{% embed helm-values.yaml versioned %} ``` diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb index e89c64ebc..c2840aa29 100644 --- a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb +++ b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins.rb @@ -2,5 +2,5 @@ require_relative "kuma-plugins/version" require_relative 'kuma-plugins/liquid/tags/jsonschema' -require_relative 'kuma-plugins/liquid/tags/embedversioned' +require_relative 'kuma-plugins/liquid/tags/embed' require_relative 'kuma-plugins/liquid/tags/policyyaml' diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embedversioned.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embed.rb similarity index 54% rename from jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embedversioned.rb rename to jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embed.rb index c7f601bb6..4c1976cfb 100644 --- a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embedversioned.rb +++ b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/embed.rb @@ -2,16 +2,23 @@ module Jekyll module KumaPlugins module Liquid module Tags - class EmbedVersioned < ::Liquid::Tag + class Embed < ::Liquid::Tag def initialize(tag_name, markup, options) super - @file = @markup.strip + params = {} + @file, *params_list = @markup.split(' ') + params_list.each do |item| + sp = item.split('=') + params[sp[0]] = sp[1] + end + @versioned = params.has_key?('versioned') end def render(context) base_path = context.registers[:site].config.fetch('mesh_raw_generated_path', 'app/docs') release = context.registers[:page]['release'] - path = "#{base_path}/#{release}/generated/raw/#{@file}" + path = File.join(base_path, @versioned ? release : '', @file) + File.read(path) rescue begin Jekyll.logger.warn("Failed reading raw file", path) return @@ -22,4 +29,4 @@ def render(context) end end end -Liquid::Template.register_tag('embed_versioned', Jekyll::KumaPlugins::Liquid::Tags::EmbedVersioned) +Liquid::Template.register_tag('embed', Jekyll::KumaPlugins::Liquid::Tags::Embed) diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb index ce67fcdfe..04ebf4332 100644 --- a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb +++ b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb @@ -20,7 +20,7 @@ def initialize(tag_name, markup, options) def render(context) release = context.registers[:page]['release'] base_path = context.registers[:site].config.fetch('mesh_raw_generated_path', 'app/docs') - data = @type.load("#{base_path}/#{release}/generated/raw") + data = @type.load("#{base_path}/#{release}") <<~TIP
From 296897525ac21b378d0843beb3a41ac33a72b628 Mon Sep 17 00:00:00 2001 From: Charly Molter Date: Tue, 4 Jul 2023 12:08:56 +0200 Subject: [PATCH 3/4] exclude github pull Signed-off-by: Charly Molter --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dee471cc6..5d94cab86 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,10 +40,10 @@ jobs: max_timeout: 1200 - name: link checker run: | - `go env GOPATH`/bin/muffet ${URL} --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --rate-limit 50 --timeout 60 + `go env GOPATH`/bin/muffet ${URL} --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/kumahq/kuma/pull' --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --rate-limit 50 --timeout 60 - name: link checker dev docs run: | - `go env GOPATH`/bin/muffet ${URL}/docs/dev --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --exclude https://download.konghq.com --rate-limit 50 --timeout 60 + `go env GOPATH`/bin/muffet ${URL}/docs/dev --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/kumahq/kuma/pull' --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --exclude https://download.konghq.com --rate-limit 50 --timeout 60 installer-sh: name: Test installer.sh From 28b61c2d7969484df1b6d85badaee581295c59ee Mon Sep 17 00:00:00 2001 From: Bart Smykla Date: Wed, 5 Jul 2023 04:48:08 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Signed-off-by: Bart Smykla --- .github/workflows/ci.yml | 4 ++-- app/_src/policies/meshgatewayinstance.md | 2 +- .../lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5d94cab86..145e7f8d5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,10 +40,10 @@ jobs: max_timeout: 1200 - name: link checker run: | - `go env GOPATH`/bin/muffet ${URL} --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/kumahq/kuma/pull' --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --rate-limit 50 --timeout 60 + $(go env GOPATH)/bin/muffet ${URL} --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/kumahq/kuma/pull' --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --rate-limit 50 --timeout 60 - name: link checker dev docs run: | - `go env GOPATH`/bin/muffet ${URL}/docs/dev --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/kumahq/kuma/pull' --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --exclude https://download.konghq.com --rate-limit 50 --timeout 60 + $(go env GOPATH)/bin/muffet ${URL}/docs/dev --buffer-size 8192 --exclude https://twitter.com --max-connections-per-host=8 --exclude 127.0.0.1 --exclude 'https://github.com/kumahq/kuma/pull' --exclude 'https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md.*' --exclude https://download.konghq.com --rate-limit 50 --timeout 60 installer-sh: name: Test installer.sh diff --git a/app/_src/policies/meshgatewayinstance.md b/app/_src/policies/meshgatewayinstance.md index 0681e010f..99984a5b6 100644 --- a/app/_src/policies/meshgatewayinstance.md +++ b/app/_src/policies/meshgatewayinstance.md @@ -120,6 +120,6 @@ spec: {% endif_version %} -## schema +## Schema {% json_schema kuma.io_meshgatewayinstances type=crd %} diff --git a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb index 04ebf4332..212fc075e 100644 --- a/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb +++ b/jekyll-kuma-plugins/lib/jekyll/kuma-plugins/liquid/tags/jsonschema.rb @@ -23,11 +23,11 @@ def render(context) data = @type.load("#{base_path}/#{release}") <<~TIP -
+
TIP