From 1a9c2d8e9d1b9a452c2ef3358747c68fea4b5a45 Mon Sep 17 00:00:00 2001 From: Saurabh Parekh Date: Wed, 3 Apr 2024 15:04:39 -0700 Subject: [PATCH] Add apiServerExtraArgs as optional configuration to docs (#7853) * Add apiServerExtraArgs as an optional configuration to docs * Add mini design doc for configuring api server extra args --- designs/api-server-extra-args.md | 118 ++++++++++++++++++ .../getting-started/baremetal/bare-spec.md | 1 + .../getting-started/cloudstack/cloud-spec.md | 1 + .../getting-started/nutanix/nutanix-spec.md | 1 + .../optional/api-server-extra-args.md | 38 ++++++ .../en/docs/getting-started/snow/snow-spec.md | 1 + .../getting-started/vsphere/vsphere-spec.md | 1 + 7 files changed, 161 insertions(+) create mode 100644 designs/api-server-extra-args.md create mode 100644 docs/content/en/docs/getting-started/optional/api-server-extra-args.md diff --git a/designs/api-server-extra-args.md b/designs/api-server-extra-args.md new file mode 100644 index 000000000000..48fef999e4a0 --- /dev/null +++ b/designs/api-server-extra-args.md @@ -0,0 +1,118 @@ +# Allow users to configure kube-apiserver flags + +## Problem Statement + +A customer is currently using OIDC for authenticating the kubernetes service accounts(KSA) and they need some mechanism to configure the kube-apiserver flags for their usecase. The main issue that we are addressing in this document is how we want to allow users to be able to configure these flags. + +## Overview of Solution + +Allow users to configure the flags by exposing a map in the cluster spec yaml + +**Schema:** + +```yaml +apiVersion: anywhere.eks.amazonaws.com/v1alpha1 +kind: Cluster +metadata: + name: mgmt-cluster +spec: + ... + controlPlaneConfiguration: + ... + # More control plane components can be added here in the future + apiServerExtraArgs: + ... + "service-account-issuer": "https://{my-service-account-issuer-url}" + "service-account-jwks-uri": "https://{my-service-account-issuer-url}/openid/v1/jwks" + "service-account-signing-key-file": "/etc/kubernetes/pki/sa.key" + "service-account-key-file": "/etc/kubernetes/pki/sa.pub" +``` + +**Validations:** + +* Validate that oidc flags are not configured in apiServerExtraArgs if OIDCConfig identity provider is already configured in the spec +* Validate that the feature flag is enabled for configuring apiServerExtraArgs + +**Pros:** + +* Creates a standard way of exposing any flag for the control plane components +* Gives more flexibility to the users in terms of validating the flag values for the api-server + +**Cons:** + +* Does not enforce OIDC compliance or any other validations on the allowed values for the flags + +## Alternate Solutions + +Allow users to configure the flags as a struct field in the cluster spec yaml + +**Schema:** + +```yaml +apiVersion: anywhere.eks.amazonaws.com/v1alpha1 +kind: Cluster +metadata: + name: mgmt-cluster +spec: + ... + controlPlaneConfiguration: + ... + apiServerConfiguration: + ... + serviceAccountIssuer: + - "https://{my-service-account-issuer-url}" + serviceAccountJwksUri: "https://{my-service-account-issuer-url}/openid/v1/jwks" + serviceAccountSigningKeyFile: "/etc/kubernetes/pki/sa.key" + serviceAccountKeyFile: "/etc/kubernetes/pki/sa.pub" +``` + +**Validations:** + +* Validate that both serviceAccountIssuer and serviceAccountJwksUri have same domain and use https scheme +* Additional set of validations specific to each of the flags + +**Pros:** + +* Fails fast if any of the flags are misconfigured with invalid values +* Allows enforcing OIDC compliance for the service account flags of the api-server + +**Cons:** + +* Gives less flexibility to the users for configuring the flags in terms of number of validations +* Does not provide a standard way to configure the flags +* Difficult to validate each and every flag and debug any issues with apiserver + +## Implementation Details + +``` +apiServerExtraArgs: + "service-account-issuer": "https://{my-service-account-issuer-url}" + "service-account-jwks-uri": "https://{my-service-account-issuer-url}/openid/v1/jwks" +``` + +https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/control-plane-flags/#apiserver-flags +These flags will be fetched from the cluster spec and added to the apiServerExtraArgs in the ClusterConfiguration object during create and upgrade operations for generating control plane CAPI spec + +Users need to enable the feature flag `API_SERVER_EXTRA_ARGS_ENABLED=true` to configure the api server flags in the cluster spec. If it's not enabled, then it will throw an error when validating the cluster spec. This is done in order to expose this functionality for now before we determine to support it officially with some more robust validations. + +The `service-account-issuer` flag can be configured for both podIamConfig as well as controlPlaneConfiguration to enable both features. If both are configured, the podIamConfig url will be appended to the controlPlaneConfiguration url. + +If OIDCConfig is specified in the identityProviderRefs within the spec, then oidc flags cannot be configured in the apiServerExtraArgs and the CLI will throw an error. + +## Documentation + +We would have to add `controlPlaneConfiguration.apiServerExtraArgs` as an optional configuration for the cluster spec in our EKS-A docs + +## Migration plan for existing flags + +* Phase 1: We can add more flags to the above options and have validations for the existing flags configured in some other fields to make sure that there is no conflict between them and allow only one of them to be configured +* Phase 2: We can decide on the priority among the existing conflicting fields and if the flags are configured in multiple fields, the one with higher priority will have precedence and will be used in the cluster +* Phase 3: We can deprecate all the lower priority conflicting fields for the existing flags and have only one standardized way of configuring all the flags + +## References + +* https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/1393-oidc-discovery +* https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#service-account-issuer-discovery +* https://openid.net/developers/how-connect-works/ +* https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow + diff --git a/docs/content/en/docs/getting-started/baremetal/bare-spec.md b/docs/content/en/docs/getting-started/baremetal/bare-spec.md index 8e5a9d05515d..6b256cab3a2a 100644 --- a/docs/content/en/docs/getting-started/baremetal/bare-spec.md +++ b/docs/content/en/docs/getting-started/baremetal/bare-spec.md @@ -19,6 +19,7 @@ The following additional optional configuration can also be included: * [OIDC]({{< relref "../optional/oidc.md" >}}) * [Registry Mirror]({{< relref "../optional/registrymirror.md" >}}) * [Machine Health Check Timeouts]({{< relref "../optional/healthchecks.md" >}}) +* [API Server Extra Args]({{< relref "../optional/api-server-extra-args.md" >}}) To generate your own cluster configuration, follow instructions from the [Create Bare Metal cluster]({{< relref "./baremetal-getstarted" >}}) section and modify it using descriptions below. For information on how to add cluster configuration settings to this file for advanced node configuration, see [Advanced Bare Metal cluster configuration]({{< relref "#advanced-bare-metal-cluster-configuration" >}}). diff --git a/docs/content/en/docs/getting-started/cloudstack/cloud-spec.md b/docs/content/en/docs/getting-started/cloudstack/cloud-spec.md index f2c82abdbd46..375d30fdfb4e 100644 --- a/docs/content/en/docs/getting-started/cloudstack/cloud-spec.md +++ b/docs/content/en/docs/getting-started/cloudstack/cloud-spec.md @@ -18,6 +18,7 @@ The following additional optional configuration can also be included: * [Proxy]({{< relref "../optional/proxy.md" >}}) * [Registry Mirror]({{< relref "../optional/registrymirror.md" >}}) * [Machine Health Check Timeouts]({{< relref "../optional/healthchecks.md" >}}) +* [API Server Extra Args]({{< relref "../optional/api-server-extra-args.md" >}}) ```yaml diff --git a/docs/content/en/docs/getting-started/nutanix/nutanix-spec.md b/docs/content/en/docs/getting-started/nutanix/nutanix-spec.md index efbdabdd17da..fe01d944aee5 100644 --- a/docs/content/en/docs/getting-started/nutanix/nutanix-spec.md +++ b/docs/content/en/docs/getting-started/nutanix/nutanix-spec.md @@ -20,6 +20,7 @@ The following additional optional configuration can also be included: * [Proxy]({{< relref "../optional/proxy.md" >}}) * [Gitops]({{< relref "../optional/gitops.md" >}}) * [Machine Health Check Timeouts]({{< relref "../optional/healthchecks.md" >}}) +* [API Server Extra Args]({{< relref "../optional/api-server-extra-args.md" >}}) ```yaml apiVersion: anywhere.eks.amazonaws.com/v1alpha1 diff --git a/docs/content/en/docs/getting-started/optional/api-server-extra-args.md b/docs/content/en/docs/getting-started/optional/api-server-extra-args.md new file mode 100644 index 000000000000..01846604ad3e --- /dev/null +++ b/docs/content/en/docs/getting-started/optional/api-server-extra-args.md @@ -0,0 +1,38 @@ +--- +title: "API Server Extra Args" +linkTitle: "API Server Extra Args" +weight: 60 +description: > + EKS Anywhere cluster yaml specification for Kubernetes API Server Extra Args reference +--- + +## API Server Extra Args support (optional) + +As of EKS Anywhere version v0.20.0, you can pass additional flags to configure the Kubernetes API server in your EKS Anywhere clusters. + +#### Provider support details +| | vSphere | Bare Metal | Nutanix | CloudStack | Snow | +|:--------------:|:-------:|:----------:|:-------:|:----------:|:----:| +| **Supported?** | ✓ | ✓ | ✓ | ✓ | ✓ | + +In order to configure a cluster with API Server extra args, you need to configure your cluster by updating the cluster configuration file to include the details below. The feature flag `API_SERVER_EXTRA_ARGS_ENABLED=true` needs to be set as an environment variable. + +This is a generic template with some example API Server extra args configuration below for reference: +```yaml +apiVersion: anywhere.eks.amazonaws.com/v1alpha1 +kind: Cluster +metadata: + name: my-cluster-name +spec: + ... + controlPlaneConfiguration: + apiServerExtraArgs: + ... + disable-admission-plugins: "DefaultStorageClass,DefaultTolerationSeconds" + enable-admission-plugins: "NamespaceAutoProvision,NamespaceExists" +``` + +The above example configures the `disable-admission-plugins` and `enable-admission-plugins` options of the API Server to enable additional admission plugins or disable some of the default ones. You can configure any of the API Server options using the above template. + +### controlPlaneConfiguration.apiServerExtraArgs (optional) +Reference the [Kubernetes documentation](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/#options) for the list of flags that can be configured for the Kubernetes API server in EKS Anywhere \ No newline at end of file diff --git a/docs/content/en/docs/getting-started/snow/snow-spec.md b/docs/content/en/docs/getting-started/snow/snow-spec.md index 096bbdb9efa9..31f81aab96df 100644 --- a/docs/content/en/docs/getting-started/snow/snow-spec.md +++ b/docs/content/en/docs/getting-started/snow/snow-spec.md @@ -18,6 +18,7 @@ The following additional optional configuration can also be included: * [Proxy]({{< relref "../optional/proxy.md" >}}) * [Registry Mirror]({{< relref "../optional/registrymirror.md" >}}) * [Machine Health Check Timeouts]({{< relref "../optional/healthchecks.md" >}}) +* [API Server Extra Args]({{< relref "../optional/api-server-extra-args.md" >}}) ```yaml apiVersion: anywhere.eks.amazonaws.com/v1alpha1 diff --git a/docs/content/en/docs/getting-started/vsphere/vsphere-spec.md b/docs/content/en/docs/getting-started/vsphere/vsphere-spec.md index d8104ee6c58f..dedfd422c6aa 100644 --- a/docs/content/en/docs/getting-started/vsphere/vsphere-spec.md +++ b/docs/content/en/docs/getting-started/vsphere/vsphere-spec.md @@ -111,6 +111,7 @@ The following additional optional configuration can also be included: * [Registry Mirror]({{< relref "../optional/registrymirror.md" >}}) * [Host OS Config]({{< relref "../optional/hostOSConfig.md" >}}) * [Machine Health Check Timeouts]({{< relref "../optional/healthchecks.md" >}}) +* [API Server Extra Args]({{< relref "../optional/api-server-extra-args.md" >}}) ## Cluster Fields