diff --git a/website/docs/runtime-flags.md b/website/docs/runtime-flags.md new file mode 100644 index 00000000000..99d65c57f61 --- /dev/null +++ b/website/docs/runtime-flags.md @@ -0,0 +1,69 @@ +--- +id: runtime-flags +title: Runtime Flags +--- + +## Runtime Flags +The following flags can be used to configure Gatekeeper's runtime behavior: + +| Flag | Default Value | Description | +|------------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--log-file` | `""` | Log to file, if specified. Default is to log to stderr. | +| `--log-level` | `"INFO"` | Minimum log level. For example, DEBUG, INFO, WARNING, ERROR. Defaulted to INFO if unspecified. | +| `--log-level-key` | `"level"` | JSON key for the log level field, defaults to `level` | +| `--log-level-encoder` | `"lower"` | Encoder for the value of the log level field. Valid values: [`lower`, `capital`, `color`, `capitalcolor`], default: `lower` | +| `--health-addr` | `":9090"` | The address to which the health endpoint binds. | +| `--metrics-addr` | `"0"` | The address the metric endpoint binds to. | +| `--port` | `443` | Port for the server. defaulted to 443 if unspecified. | +| `--host` | `""` | The host address the webhook server listens on. defaults to all addresses. | +| `--cert-dir` | `"/certs"` | The directory where certs are stored, defaults to /certs. | +| `--disable-cert-rotation` | `false` | Disable automatic generation and rotation of webhook TLS certificates/keys. | +| `--enable-pprof` | `false` | Enable `pprof` profiling. | +| `--pprof-port` | `6060` | Port for `pprof` profiling. defaulted to 6060 if unspecified. | +| `--cert-service-name` | `"gatekeeper-webhook-service"` | The service name used to generate the TLS cert's hostname. Defaults to gatekeeper-webhook-service. | +| `--enable-tls-healthcheck` | `false` | Enable probing webhook API with certificate stored in certDir. | +| `--enable-k8s-native-validation` | `true` | Enable the validating admission policy driver. | +| `--external-data-provider-response-cache-ttl` | `3m` | TTL for the external data provider response cache. Specify the duration in 'h', 'm', or 's' for hours, minutes, or seconds respectively. Defaults to 3 minutes if unspecified. Setting the TTL to 0 disables the cache. | +| `--audit-interval` | `60` | Interval to run audit in seconds. defaulted to 60 secs if unspecified, 0 to disable. | +| `--constraint-violations-limit` | `20` | Limit of number of violations per constraint. defaulted to 20 violations if unspecified. | +| `--audit-chunk-size` | `500` | (alpha) Kubernetes API chunking List results when retrieving cluster resources using discovery client. defaulted to 500 if unspecified. | +| `--audit-from-cache` | `false` | Audit synced resources from internal cache, bypassing direct queries to Kubernetes API server. | +| `--emit-audit-events` | `false` | (alpha) Emit Kubernetes events with detailed info for each violation from an audit. | +| `--audit-events-involved-namespace` | `false` | Emit audit events for each violation in the involved objects namespace, the default (false) generates events in the namespace Gatekeeper is installed in. Audit events from cluster-scoped resources will still follow the default behavior. | +| `--audit-match-kind-only` | `false` | Only use kinds specified in all constraints for auditing cluster resources. if kind is not specified in any of the constraints, it will audit all resources (same as setting this flag to false). | +| `--api-cache-dir` | `"/tmp/audit"` | The directory where audit from api server cache are stored, defaults to /tmp/audit. | +| `--audit-connection` | `"audit-connection"` | (alpha) Connection name for publishing audit violation messages. Defaults to audit-connection. | +| `--audit-channel` | `"audit-channel"` | (alpha) Channel name for publishing audit violation messages. Defaults to audit-channel. | +| `--log-stats-audit` | `false` | (alpha) Log stats metrics for the audit run. | +| `--default-create-vap-binding-for-constraints` | `false` | (alpha) Create VAPBinding resource for constraint of the template containing VAP-style CEL source. Allowed values are false: do not create Validating Admission Policy Binding, true: create Validating Admission Policy Binding. | +| `--default-create-vap-for-templates` | `false` | (alpha) Create VAP resource for template containing VAP-style CEL source. Allowed values are false: do not create Validating Admission Policy unless generateVAP: true is set on constraint template explicitly, true: create Validating Admission Policy unless generateVAP: false is set on constraint template explicitly. | +| `--default-wait-for-vapb-generation` | `30` | (alpha) Wait time in seconds before generating a ValidatingAdmissionPolicyBinding after a constraint CRD is created. | +| `--debug-use-fake-pod` | `false` | Use a fake pod name so the Gatekeeper executable can be run outside of Kubernetes. | +| `--enable-pub-sub` | `false` | (alpha) Enabled pubsub to publish messages. | +| `--enable-generator-resource-expansion` | `true` | (beta) Enable the expansion of generator resources. | +| `--enable-external-data` | `true` | Enable external data feature. | +| `--otlp-endpoint` | `""` | Opentelemetry exporter endpoint. | +| `--otlp-metric-interval` | `10s` | Interval to read metrics for opentelemetry exporter. Defaulted to 10 secs if unspecified. | +| `--prometheus-port` | `8888` | Prometheus port for metrics backend. | +| `--stackdriver-only-when-available` | `false` | Only attempt to start the stackdriver exporter if credentials are available. | +| `--stackdriver-metric-interval` | `10s` | Interval to read metrics for stackdriver exporter. defaulted to 10 secs if unspecified. | +| `--metrics-backend` | `prometheus` | Backend used for metrics. e.g. `prometheus`, `stackdriver`. This flag can be declared more than once. Omitting will default to supporting `prometheus`. | +| `--enable-mutation` | `false` | Deprecated. This used to enable the mutation feature, now it has no effect. Use --operation=mutation-webhook and --operation=mutation-status instead. | +| `--log-mutations` | `false` | Enable detailed logging of mutation events. | +| `--mutation-annotations` | `false` | Enable mutation annotations. | +| `--operation` | None | The operation to be performed by this instance. e.g. audit, webhook. This flag can be declared more than once. Omitting will default to supporting all operations. | +| `--readiness-retries` | `0` | The number of resource ingestion attempts allowed before the resource is disregarded. A value of -1 will retry indefinitely. | +| `--disable-enforcementaction-validation` | `false` | Disable validation of the enforcementAction and scopedEnforcementActions field of a constraint. | +| `--log-denies` | `false` | Log detailed info on each deny. | +| `--emit-admission-events` | `false` | (alpha) Emit Kubernetes events for each admission violation. | +| `--admission-events-involved-namespace` | `false` | Emit admission events for each violation in the involved objects namespace, the default (false) generates events in the namespace Gatekeeper is installed in. Admission events from cluster-scoped resources will still follow the default behavior. | +| `--log-stats-admission` | `false` | (alpha) Log stats for admission webhook. | +| `--validating-webhook-configuration-name` | `"gatekeeper-validating-webhook-configuration"` | Name of the ValidatingWebhookConfiguration. | +| `--mutating-webhook-configuration-name` | `"gatekeeper-mutating-webhook-configuration"` | Name of the MutatingWebhookConfiguration. | +| `--tls-min-version` | `"1.3"` | Minimum version of TLS supported. | +| `--client-ca-name` | `""` | Name of the certificate authority bundle to authenticate the Kubernetes API server requests against. | +| `--client-cn-name` | `"kube-apiserver"` | Expected CN name on the client certificate attached by apiserver in requests to the webhook. | +| `--exempt-namespace` | None | The specified namespace is allowed to set the admission.gatekeeper.sh/ignore label. To exempt multiple namespaces, this flag can be declared more than once. | +| `--exempt-namespace-prefix` | None | A namespace with the specified prefix is allowed to set the admission.gatekeeper.sh/ignore label. To exempt multiple prefixes, this flag can be declared more than once. | +| `--exempt-namespace-suffix` | None | A namespace with the specified suffix is allowed to set the admission.gatekeeper.sh/ignore label. To exempt multiple suffixes, this flag can be declared more than once. | +| `--max-serving-threads` | `-1` | Cap the number of threads handling non-trivial requests, -1 caps the number of threads to GOMAXPROCS. Defaults to -1. | diff --git a/website/sidebars.js b/website/sidebars.js index f81ac8de716..16b66f8f9bb 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -36,7 +36,8 @@ module.exports = { 'workload-resources', 'pubsub', 'validating-admission-policy', - 'enforcement-points' + 'enforcement-points', + 'runtime-flags' ], }, { diff --git a/website/versioned_docs/version-v3.18.x/runtime-flags.md b/website/versioned_docs/version-v3.18.x/runtime-flags.md new file mode 100644 index 00000000000..99d65c57f61 --- /dev/null +++ b/website/versioned_docs/version-v3.18.x/runtime-flags.md @@ -0,0 +1,69 @@ +--- +id: runtime-flags +title: Runtime Flags +--- + +## Runtime Flags +The following flags can be used to configure Gatekeeper's runtime behavior: + +| Flag | Default Value | Description | +|------------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--log-file` | `""` | Log to file, if specified. Default is to log to stderr. | +| `--log-level` | `"INFO"` | Minimum log level. For example, DEBUG, INFO, WARNING, ERROR. Defaulted to INFO if unspecified. | +| `--log-level-key` | `"level"` | JSON key for the log level field, defaults to `level` | +| `--log-level-encoder` | `"lower"` | Encoder for the value of the log level field. Valid values: [`lower`, `capital`, `color`, `capitalcolor`], default: `lower` | +| `--health-addr` | `":9090"` | The address to which the health endpoint binds. | +| `--metrics-addr` | `"0"` | The address the metric endpoint binds to. | +| `--port` | `443` | Port for the server. defaulted to 443 if unspecified. | +| `--host` | `""` | The host address the webhook server listens on. defaults to all addresses. | +| `--cert-dir` | `"/certs"` | The directory where certs are stored, defaults to /certs. | +| `--disable-cert-rotation` | `false` | Disable automatic generation and rotation of webhook TLS certificates/keys. | +| `--enable-pprof` | `false` | Enable `pprof` profiling. | +| `--pprof-port` | `6060` | Port for `pprof` profiling. defaulted to 6060 if unspecified. | +| `--cert-service-name` | `"gatekeeper-webhook-service"` | The service name used to generate the TLS cert's hostname. Defaults to gatekeeper-webhook-service. | +| `--enable-tls-healthcheck` | `false` | Enable probing webhook API with certificate stored in certDir. | +| `--enable-k8s-native-validation` | `true` | Enable the validating admission policy driver. | +| `--external-data-provider-response-cache-ttl` | `3m` | TTL for the external data provider response cache. Specify the duration in 'h', 'm', or 's' for hours, minutes, or seconds respectively. Defaults to 3 minutes if unspecified. Setting the TTL to 0 disables the cache. | +| `--audit-interval` | `60` | Interval to run audit in seconds. defaulted to 60 secs if unspecified, 0 to disable. | +| `--constraint-violations-limit` | `20` | Limit of number of violations per constraint. defaulted to 20 violations if unspecified. | +| `--audit-chunk-size` | `500` | (alpha) Kubernetes API chunking List results when retrieving cluster resources using discovery client. defaulted to 500 if unspecified. | +| `--audit-from-cache` | `false` | Audit synced resources from internal cache, bypassing direct queries to Kubernetes API server. | +| `--emit-audit-events` | `false` | (alpha) Emit Kubernetes events with detailed info for each violation from an audit. | +| `--audit-events-involved-namespace` | `false` | Emit audit events for each violation in the involved objects namespace, the default (false) generates events in the namespace Gatekeeper is installed in. Audit events from cluster-scoped resources will still follow the default behavior. | +| `--audit-match-kind-only` | `false` | Only use kinds specified in all constraints for auditing cluster resources. if kind is not specified in any of the constraints, it will audit all resources (same as setting this flag to false). | +| `--api-cache-dir` | `"/tmp/audit"` | The directory where audit from api server cache are stored, defaults to /tmp/audit. | +| `--audit-connection` | `"audit-connection"` | (alpha) Connection name for publishing audit violation messages. Defaults to audit-connection. | +| `--audit-channel` | `"audit-channel"` | (alpha) Channel name for publishing audit violation messages. Defaults to audit-channel. | +| `--log-stats-audit` | `false` | (alpha) Log stats metrics for the audit run. | +| `--default-create-vap-binding-for-constraints` | `false` | (alpha) Create VAPBinding resource for constraint of the template containing VAP-style CEL source. Allowed values are false: do not create Validating Admission Policy Binding, true: create Validating Admission Policy Binding. | +| `--default-create-vap-for-templates` | `false` | (alpha) Create VAP resource for template containing VAP-style CEL source. Allowed values are false: do not create Validating Admission Policy unless generateVAP: true is set on constraint template explicitly, true: create Validating Admission Policy unless generateVAP: false is set on constraint template explicitly. | +| `--default-wait-for-vapb-generation` | `30` | (alpha) Wait time in seconds before generating a ValidatingAdmissionPolicyBinding after a constraint CRD is created. | +| `--debug-use-fake-pod` | `false` | Use a fake pod name so the Gatekeeper executable can be run outside of Kubernetes. | +| `--enable-pub-sub` | `false` | (alpha) Enabled pubsub to publish messages. | +| `--enable-generator-resource-expansion` | `true` | (beta) Enable the expansion of generator resources. | +| `--enable-external-data` | `true` | Enable external data feature. | +| `--otlp-endpoint` | `""` | Opentelemetry exporter endpoint. | +| `--otlp-metric-interval` | `10s` | Interval to read metrics for opentelemetry exporter. Defaulted to 10 secs if unspecified. | +| `--prometheus-port` | `8888` | Prometheus port for metrics backend. | +| `--stackdriver-only-when-available` | `false` | Only attempt to start the stackdriver exporter if credentials are available. | +| `--stackdriver-metric-interval` | `10s` | Interval to read metrics for stackdriver exporter. defaulted to 10 secs if unspecified. | +| `--metrics-backend` | `prometheus` | Backend used for metrics. e.g. `prometheus`, `stackdriver`. This flag can be declared more than once. Omitting will default to supporting `prometheus`. | +| `--enable-mutation` | `false` | Deprecated. This used to enable the mutation feature, now it has no effect. Use --operation=mutation-webhook and --operation=mutation-status instead. | +| `--log-mutations` | `false` | Enable detailed logging of mutation events. | +| `--mutation-annotations` | `false` | Enable mutation annotations. | +| `--operation` | None | The operation to be performed by this instance. e.g. audit, webhook. This flag can be declared more than once. Omitting will default to supporting all operations. | +| `--readiness-retries` | `0` | The number of resource ingestion attempts allowed before the resource is disregarded. A value of -1 will retry indefinitely. | +| `--disable-enforcementaction-validation` | `false` | Disable validation of the enforcementAction and scopedEnforcementActions field of a constraint. | +| `--log-denies` | `false` | Log detailed info on each deny. | +| `--emit-admission-events` | `false` | (alpha) Emit Kubernetes events for each admission violation. | +| `--admission-events-involved-namespace` | `false` | Emit admission events for each violation in the involved objects namespace, the default (false) generates events in the namespace Gatekeeper is installed in. Admission events from cluster-scoped resources will still follow the default behavior. | +| `--log-stats-admission` | `false` | (alpha) Log stats for admission webhook. | +| `--validating-webhook-configuration-name` | `"gatekeeper-validating-webhook-configuration"` | Name of the ValidatingWebhookConfiguration. | +| `--mutating-webhook-configuration-name` | `"gatekeeper-mutating-webhook-configuration"` | Name of the MutatingWebhookConfiguration. | +| `--tls-min-version` | `"1.3"` | Minimum version of TLS supported. | +| `--client-ca-name` | `""` | Name of the certificate authority bundle to authenticate the Kubernetes API server requests against. | +| `--client-cn-name` | `"kube-apiserver"` | Expected CN name on the client certificate attached by apiserver in requests to the webhook. | +| `--exempt-namespace` | None | The specified namespace is allowed to set the admission.gatekeeper.sh/ignore label. To exempt multiple namespaces, this flag can be declared more than once. | +| `--exempt-namespace-prefix` | None | A namespace with the specified prefix is allowed to set the admission.gatekeeper.sh/ignore label. To exempt multiple prefixes, this flag can be declared more than once. | +| `--exempt-namespace-suffix` | None | A namespace with the specified suffix is allowed to set the admission.gatekeeper.sh/ignore label. To exempt multiple suffixes, this flag can be declared more than once. | +| `--max-serving-threads` | `-1` | Cap the number of threads handling non-trivial requests, -1 caps the number of threads to GOMAXPROCS. Defaults to -1. | diff --git a/website/versioned_sidebars/version-v3.18.x-sidebars.json b/website/versioned_sidebars/version-v3.18.x-sidebars.json index 5c668a87177..3e7b519cfbd 100644 --- a/website/versioned_sidebars/version-v3.18.x-sidebars.json +++ b/website/versioned_sidebars/version-v3.18.x-sidebars.json @@ -36,7 +36,8 @@ "workload-resources", "pubsub", "validating-admission-policy", - "enforcement-points" + "enforcement-points", + "runtime-flags" ] }, {