From e726565b044cc8554678094346e726dfbd24b3be Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Sun, 25 Jun 2017 14:15:45 -0700 Subject: [PATCH] split setup-api-aggregator.md into two docs and address feedback --- _data/tasks.yml | 3 +- .../api-extension/apiserver-aggregation.md | 9 ++- .../configure-aggregation-layer.md | 52 ++++++++++++++ .../setup-api-aggregator.md | 67 ------------------- .../setup-extension-api-server.md | 53 +++++++++++++++ 5 files changed, 113 insertions(+), 71 deletions(-) create mode 100644 docs/tasks/access-kubernetes-api/configure-aggregation-layer.md delete mode 100644 docs/tasks/access-kubernetes-api/setup-api-aggregator.md create mode 100644 docs/tasks/access-kubernetes-api/setup-extension-api-server.md diff --git a/_data/tasks.yml b/_data/tasks.yml index fd52a93cfb1c4..6f29760069178 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -96,7 +96,8 @@ toc: - docs/tasks/access-kubernetes-api/http-proxy-access-api.md - docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions.md - docs/tasks/access-kubernetes-api/extend-api-third-party-resource.md - - docs/tasks/access-kubernetes-api/setup-api-aggregator.md + - docs/tasks/access-kubernetes-api/configure-aggregation-layer.md + - docs/tasks/access-kubernetes-api/setup-extension-api-server.md - title: TLS section: diff --git a/docs/concepts/api-extension/apiserver-aggregation.md b/docs/concepts/api-extension/apiserver-aggregation.md index ab3e4858f5074..5e2359afd6699 100644 --- a/docs/concepts/api-extension/apiserver-aggregation.md +++ b/docs/concepts/api-extension/apiserver-aggregation.md @@ -1,6 +1,8 @@ --- -title: Extending the Kubernetes API with Aggregator +title: Extending the Kubernetes API with the aggregation layer assignees: +- lavalamp +- cheftako - chenopis --- @@ -24,8 +26,9 @@ In 1.7 the aggregation layer runs in-process with the kube-apiserver. Until an e {% capture whatsnext %} -* To get the aggregator working in your environment, see [Setup the API aggregator](/docs/tasks/access-kubernetes-api/setup-api-aggregator/). -* Learn how to [Extend the Kubernetes API Using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/). +* To get the aggregator working in your environment, [configure the aggregation layer](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/). +* Then, [setup an extension api-server](/docs/tasks/access-kubernetes-api/setup-extension-api-server/) to work with the aggregation layer. +* Also, learn how to [extend the Kubernetes API using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/). {% endcapture %} diff --git a/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md b/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md new file mode 100644 index 0000000000000..f33f17869ee2d --- /dev/null +++ b/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md @@ -0,0 +1,52 @@ +--- +title: Configure the aggregation layer +assignees: +- lavalamp +- cheftako +- chenopis +--- + +{% capture overview %} + +Configuring the aggregation layer allows the Kubernetes apiserver to be extended with additional APIs, which are not part of the core Kubernetes APIs. + +{% endcapture %} + +{% capture prerequisites %} + +* You need to have a Kubernetes cluster running. + +**Note:** There are a few setup requirements for getting the aggregation layer working in your environment to support mutual TLS auth between the proxy and extension apiservers. Kubernetes and the kube-apiserver have multiple CAs, so make sure that the proxy is signed by the aggregation layer CA and not by something else, like the master CA. + +{% endcapture %} + +{% capture steps %} + +## Enable apiserver flags + +Enable the aggregation layer via the following apiserver flags. They may have already been taken care of by your provider. + + --requestheader-client-ca-file= + --requestheader-allowed-names=aggregator + --requestheader-extra-headers-prefix=X-Remote-Extra- + --requestheader-group-headers=X-Remote-Group + --requestheader-username-headers=X-Remote-User + --proxy-client-cert-file= + --proxy-client-key-file= + +The [Kubernetes Architectural Roadmap](https://docs.google.com/a/google.com/document/d/1XkjVm4bOeiVkj-Xt1LgoGiqWsBfNozJ51dyI-ljzt1o/edit?usp=sharing) recommends not running kube-proxy on the master. If you follow this recommendation, then you must make sure that the system is enabled with the following apiserver flag. Again, this may have already been taken care of by your provider. + + --enable-aggregator-routing=true + +{% endcapture %} + +{% capture whatsnext %} + +* [Setup an extension api-server](/docs/tasks/access-kubernetes-api/setup-extension-api-server/) to work with the aggregation layer. +* For a high level overview, see [Extending the Kubernetes API with Aggregator](/docs/concepts/api-extension/apiserver-aggregation/). +* Learn how to [Extend the Kubernetes API Using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/). + +{% endcapture %} + +{% include templates/task.md %} + diff --git a/docs/tasks/access-kubernetes-api/setup-api-aggregator.md b/docs/tasks/access-kubernetes-api/setup-api-aggregator.md deleted file mode 100644 index 9d4a286cbdff7..0000000000000 --- a/docs/tasks/access-kubernetes-api/setup-api-aggregator.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Setup the API Aggregator -assignees: -- chenopis ---- - -{% capture overview %} - -Setting up the API Aggregator will allow the Kubernetes apiserver to be extended with additional APIs, which are not part of the core Kubernetes APIs. - -{% endcapture %} - -{% capture prerequisites %} - -* You need to have a Kubernetes cluster running. -* Make sure there are Aggregator certificates (both CA and proxy) setup on the Kubernetes apiserver. -* The proxy cert must have been signed by the relevant CA. - -{% endcapture %} - -{% capture steps %} - -## Enable apiserver flags - -The system needs to be enabled via the following apiserver flags; however, they may have already been taken care of by your provider. - - --requestheader-client-ca-file= - --requestheader-allowed-names=aggregator - --requestheader-extra-headers-prefix=X-Remote-Extra- - --requestheader-group-headers=X-Remote-Group - --requestheader-username-headers=X-Remote-User - --proxy-client-cert-file= - --proxy-client-key-file= - -If you are not running kube-proxy on your master, as the [Kubernetes Architectural Roadmap](https://docs.google.com/a/google.com/document/d/1XkjVm4bOeiVkj-Xt1LgoGiqWsBfNozJ51dyI-ljzt1o/edit?usp=sharing) recommends, then you need to make sure that the system is enabled with the following apiserver flag. Again, this may have already been taken care of by your provider. - - --enable-aggregator-routing=true - -## Get an extension api-server working with Aggregator - -The generated skeleton, which comes with [apiserver-builder](https://github.com/Kubernetes-incubator/apiserver-builder/blob/master/README.md), should setup the skeleton server it creates to do all of these steps. You can also look at the sample-apiserver under Kubernetes for ways the following can be done. - -1. Make sure the APIService api is enabled (check --runtime-config); it is on by default, so it should be on unless it’s been deliberately turned off in your cluster. -1. You may need to make an RBAC rule allowing you to add APIService objects, or get your cluster administrator to make one. (Since API extensions affect the entire cluster, it is not recommended to do testing/development/debug of an API extension in a live cluster.) -1. Create the Kubernetes namespace you want to run your extension api-service in. -1. Create/get a CA cert to be used to sign the server cert the extension api-server uses for HTTPS. -1. Create a server cert/key for the api-server to use for HTTPS. This cert should be signed by the above CA. It should also have a CN of the Kube DNS name. This will generally be derived from the Kubernetes service and be of the form ..svc -1. Create a Kubernetes secret with the server cert/key in your namespace. -1. Create a Kubernetes deployment for the extension api-server and make sure you are loading the secret as a volume. It will also need to contain a reference to a working image of your extension api-server. The deployment should also be in your namespace. -1. Make sure that your extension-apiserver loads those certs from that volume and that they are used in the HTTPS handshake. -1. Create a Kubernetes service account in your namespace. -1. Create a Kubernetes cluster role for the operations you want to allow on your resources. -1. Create a Kubernetes cluster role binding from the default service account in your namespace to the cluster role you just created. -1. Create a Kubernetes apiservice. The CA cert above should be base 64 encoded, stripped of new lines and used as the spec.caBundle in the apiservce. This should not be namespaced. -1. Use kubectl to get your resource. It will probably return "No resources found." Which means that everything worked but you currently have no objects of that resource type created yet. - -{% endcapture %} - -{% capture whatsnext %} - -* For a high level overview, see [Extending the Kubernetes API with Aggregator](/docs/concepts/api-extension/apiserver-aggregation/). -* Learn how to [Extend the Kubernetes API Using Third Party Resources](/docs/tasks/access-Kubernetes-api/extend-api-third-party-resource/). - -{% endcapture %} - -{% include templates/task.md %} - diff --git a/docs/tasks/access-kubernetes-api/setup-extension-api-server.md b/docs/tasks/access-kubernetes-api/setup-extension-api-server.md new file mode 100644 index 0000000000000..a3cdea27f578c --- /dev/null +++ b/docs/tasks/access-kubernetes-api/setup-extension-api-server.md @@ -0,0 +1,53 @@ +--- +title: Setup an extension API server +assignees: +- lavalamp +- cheftako +- chenopis +--- + +{% capture overview %} + +Setting up an extension API server to work the aggregation layer allows the Kubernetes apiserver to be extended with additional APIs, which are not part of the core Kubernetes APIs. + +{% endcapture %} + +{% capture prerequisites %} + +* You need to have a Kubernetes cluster running. +* You must [configure the aggregation layer](/docs/tasks/configure-aggregation-layer) and enable the apiserver flags. + +{% endcapture %} + +{% capture steps %} + +## Setup an extension api-server to work with the aggregation layer + +If you use an existing 3rd party solution, such as [apiserver-builder](https://github.com/Kubernetes-incubator/apiserver-builder/blob/master/README.md), it should generate a skeleton and perform all of the following steps. Alternatively, you can also look at the [sample-apiserver](https://github.com/kubernetes/sample-apiserver/blob/master/README.md) under Kubernetes for ways the following can be done. + +1. Make sure the APIService API is enabled (check --runtime-config); it is on by default, so it should be on unless it’s been deliberately turned off in your cluster. +1. You may need to make an RBAC rule allowing you to add APIService objects, or get your cluster administrator to make one. (Since API extensions affect the entire cluster, it is not recommended to do testing/development/debug of an API extension in a live cluster.) +1. Create the Kubernetes namespace you want to run your extension api-service in. +1. Create/get a CA cert to be used to sign the server cert the extension api-server uses for HTTPS. +1. Create a server cert/key for the api-server to use for HTTPS. This cert should be signed by the above CA. It should also have a CN of the Kube DNS name. This is derived from the Kubernetes service and be of the form ..svc +1. Create a Kubernetes secret with the server cert/key in your namespace. +1. Create a Kubernetes deployment for the extension api-server and make sure you are loading the secret as a volume. It should contain a reference to a working image of your extension api-server. The deployment should also be in your namespace. +1. Make sure that your extension-apiserver loads those certs from that volume and that they are used in the HTTPS handshake. +1. Create a Kubernetes service account in your namespace. +1. Create a Kubernetes cluster role for the operations you want to allow on your resources. +1. Create a Kubernetes cluster role binding from the default service account in your namespace to the cluster role you just created. +1. Create a Kubernetes apiservice. The CA cert above should be base 64 encoded, stripped of new lines and used as the spec.caBundle in the apiservce. This should not be namespaced. +1. Use kubectl to get your resource. It should return "No resources found." Which means that everything worked but you currently have no objects of that resource type created yet. + +{% endcapture %} + +{% capture whatsnext %} + +* If you haven't already, [configure the aggregation layer](/docs/tasks/configure-aggregation-layer) and enable the apiserver flags. +* For a high level overview, see [Extending the Kubernetes API with Aggregator](/docs/concepts/api-extension/apiserver-aggregation/). +* Learn how to [Extend the Kubernetes API Using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/). + +{% endcapture %} + +{% include templates/task.md %} +