write a very simple getting started guide #427
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| # Getting started with Services APIs | ||
|
|
||
| ## Installing CRDs | ||
|
|
||
| This project provides a collection of Custom Resource Definitions (CRDs) that can | ||
| be installed into any Kubernetes (>= 1.16) cluster. | ||
|
|
||
| To install the CRDs, please execute: | ||
|
|
||
| ``` | ||
| kubectl kustomize "github.com/kubernetes-sigs/service-apis/config/crd?ref=master" \ | ||
| | kubectl apply -f - | ||
| ``` | ||
|
|
||
| ## Install an implementation | ||
|
|
||
| Multiple projects implement the APIs defined by this project. | ||
| You will need to either install an implementation or verify that one is already | ||
| setup for your cluster. | ||
|
|
||
| ## Sample Gateway | ||
|
|
||
| Once you have the CRDs and an implementation installed, you are ready to | ||
| use Service APIs. | ||
|
|
||
| In this example, we are installing three resources: | ||
|
|
||
| - An `acme-lb` GatewayClass which is being managed by a `acme.io/gateway-controller` | ||
| controller running in the cluster. Typically, a GatewayClass is provided by | ||
| the implementation and must be installed in the cluster. | ||
| - A Gateway which is of type `acme-lb`: | ||
| - This gateway has a single HTTP listener on port 80 which selects HTTPRoutes | ||
| from all namespaces which have the label `app: foo` on them. | ||
|
|
||
| - Finally, we have an HTTPRoute resource which is attached to the above Gateway | ||
| and has two rules: | ||
| - All requests with path beginning with `/bar` are forwarded to my-service1 | ||
| Kubernetes Service. | ||
| - All requests with path beginning with `/some/thing` AND have an HTTP header | ||
| `magic: foo` are forwarded to my-service2 Kubernetes Service. | ||
|
|
||
| With this configuration, you now have a Gateway resource which is forwarding | ||
| traffic to two Kubernetes Services based on HTTP request metadata. | ||
|
|
||
| ``` | ||
| {% include 'basic-http.yaml' %} | ||
|
There was a problem hiding this comment. I don't have a good solution for this, and this doesn't need to block the PR, but one downside of embedding examples is that the examples could actually begin to skew from the docs. Maybe we should find a way to document which examples are being used in which docs? There was a problem hiding this comment. I thought about this problem too and arrived at the same solution as you. |
||
| ``` | ||
|
|
||
| For more advanced examples, please read the other [guides](guides.md). | ||
|
|
||
| ## Uninstalling the CRDs | ||
|
|
||
|
Comment on lines
+51
to
+52
There was a problem hiding this comment. Maybe add a bit of an explanation here, something like: |
||
| To uninstall the CRDs and all resources created with them, run the following | ||
| command. Note that this will remove all GatewayClass and Gateway resources in | ||
| your cluster. If you have been using these resources for any other purpose do | ||
| not uninstall these CRDs. | ||
|
|
||
| ``` | ||
| kubectl kustomize "github.com/kubernetes-sigs/service-apis/config/crd?ref=master" \ | ||
| | kubectl delete -f - | ||
| ``` | ||
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
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
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a good way to do this without kustomize? It seems like we're not really using kustomize for anything. (This does not need to block this PR).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We do this in our Makefile too: https://github.com/kubernetes-sigs/service-apis/blob/master/Makefile#L54
Do note that the user doesn't need to install
kustomize. It is included as a plugin insidekubectlitself. Users need to make sure that theirkubectlversion is not an ancient one, which again is expected.