write a very simple getting started guide #427

hbagdi · 2020-10-27T22:24:53Z

Note

This PR builds on top of #425. Please review the last commit only.

robscott

Thanks for your work on this!

robscott · 2020-10-28T00:01:51Z

docs-src/getting-started.md

+kubectl kustomize "github.com/kubernetes-sigs/service-apis/config/crd?ref=master" \
+| kubectl apply -f -


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).

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 inside kubectl itself. Users need to make sure that their kubectl version is not an ancient one, which again is expected.

robscott · 2020-10-28T00:04:09Z

docs-src/getting-started.md

+
+## Install an implementation
+
+Service APIs is a set of specification that multiple implementations confirm to.


This doesn't feel quite right. Maybe "Multiple projects implement the APIs defined by this project."

robscott · 2020-10-28T00:04:46Z

docs-src/getting-started.md

+
+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.


Nit: This line feels too long.

robscott · 2020-10-28T00:05:46Z

docs-src/getting-started.md

+
+- 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


Nit: I'm not sure path needs to be capitalized here. I think it could use an a before it though.

robscott · 2020-10-28T00:06:02Z

docs-src/getting-started.md

+  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


Same comment as above

robscott · 2020-10-28T00:07:41Z

docs-src/getting-started.md

+Service APIs is a collection of Kubernetes Custom Resource Definitions that need
+to be installed into any Kubernetes cluster.


Maybe "This project provides a collection of Custom Resource Definitions that can be installed into any Kubernetes 1.16+ cluster."

hbagdi · 2020-10-28T15:57:45Z

Depends on #425
/hold

hbagdi · 2020-10-28T16:17:16Z

golint went missing so I rebased on master to ensure that I pull in the fixes we put in but not luck.
Is it the CI acting up?

hbagdi · 2020-10-28T16:20:46Z

/retest

robscott · 2020-10-28T17:58:50Z

@hbagdi Our verify output is super confusing, in this case it looks like another run of make generate is needed:

Uncommitted changes in generated sources:
 M docs/getting-started/index.html

hbagdi · 2020-10-29T14:52:14Z

Rebased and this should be good to go.
/hold cancel

robscott

Thanks for the work on this! Mostly LGTM, just a few nits.

docs-src/getting-started.md

robscott · 2020-10-29T22:43:43Z

docs-src/getting-started.md

+- An `acme-lb` GatewayClass which is being managed by a `acme.io/gateway-controller`
+  controller running in the cluster.


Maybe should add a note that users may want to use a GatewayClass provided by the implementation installed in their cluster. If one is not provided, they should ensure that the controller name used here matches a controller name supported by an implementation installed in their cluster.

If one is not provided

Skipped this part. We shouldn't be encouraging implementers not providing a GatewayClass right now.

robscott · 2020-10-29T22:47:14Z

docs-src/getting-started.md

+traffic to two Kubernetes Services based on HTTP request metadata.
+
+```
+{% include 'basic-http.yaml' %}


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?

I thought about this problem too and arrived at the same solution as you.
Essentially adding a link to the guide file as a yaml comment.
Let's continue this in #446.

docs-src/getting-started.md

hbagdi · 2020-11-02T17:22:45Z

@robscott Updated. PTAL.

robscott

Thanks for your work on this! Just a couple small things but otherwise LGTM.

robscott · 2020-11-04T19:45:26Z

docs-src/getting-started.md

+    - 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 reource which is forwarding


Suggested change

With this configuration, you now have a Gateway reource which is forwarding

With this configuration, you now have a Gateway resource which is forwarding

robscott · 2020-11-04T19:48:20Z

docs-src/getting-started.md

+## Uninstalling the CRDs
+


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.

youngnick

This is looking great.

Co-authored-by: Rob Scott <[email protected]>

hbagdi · 2020-11-05T14:55:07Z

@robscott Updated. PTAL.

robscott · 2020-11-05T16:38:37Z

Thanks!

/lgtm
/approve

k8s-ci-robot · 2020-11-05T16:38:48Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: hbagdi, robscott

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [robscott]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Oct 27, 2020

k8s-ci-robot requested review from bowei and robscott October 27, 2020 22:25

This was referenced Oct 27, 2020

Add a User Guide to documentation #332

Closed

Add examples to documentation #333

Closed

robscott reviewed Oct 28, 2020

View reviewed changes

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Oct 28, 2020

hbagdi force-pushed the getting-started-guide branch 2 times, most recently from 8502d40 to f6a78f3 Compare October 28, 2020 16:09

hbagdi force-pushed the getting-started-guide branch 2 times, most recently from 54b393f to a50ca52 Compare October 29, 2020 14:51

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Oct 29, 2020

robscott reviewed Oct 29, 2020

View reviewed changes

hbagdi force-pushed the getting-started-guide branch from 92e712d to 8b66933 Compare November 2, 2020 17:22

hbagdi added the priority/critical-urgent Highest priority. Must be actively worked on as someone's top priority right now. label Nov 2, 2020

robscott reviewed Nov 4, 2020

View reviewed changes

youngnick reviewed Nov 5, 2020

View reviewed changes

write a getting started guide

40beb1b

Co-authored-by: Rob Scott <[email protected]>

hbagdi force-pushed the getting-started-guide branch from 8b66933 to 40beb1b Compare November 5, 2020 14:54

k8s-ci-robot assigned robscott Nov 5, 2020

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 5, 2020

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 5, 2020

k8s-ci-robot merged commit edcbeaa into kubernetes-sigs:master Nov 5, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

write a very simple getting started guide #427

write a very simple getting started guide #427

hbagdi commented Oct 27, 2020

robscott left a comment

robscott Oct 28, 2020

hbagdi Oct 28, 2020

robscott Oct 28, 2020

robscott Oct 28, 2020

robscott Oct 28, 2020

robscott Oct 28, 2020

robscott Oct 28, 2020

hbagdi commented Oct 28, 2020

hbagdi commented Oct 28, 2020

hbagdi commented Oct 28, 2020

robscott commented Oct 28, 2020

hbagdi commented Oct 29, 2020

robscott left a comment

robscott Oct 29, 2020

hbagdi Nov 2, 2020

robscott Oct 29, 2020

hbagdi Nov 2, 2020

hbagdi commented Nov 2, 2020

robscott left a comment •

edited

Loading

robscott Nov 4, 2020

robscott Nov 4, 2020

youngnick left a comment

hbagdi commented Nov 5, 2020

robscott commented Nov 5, 2020

k8s-ci-robot commented Nov 5, 2020

		kubectl kustomize "github.com/kubernetes-sigs/service-apis/config/crd?ref=master" \
		\| kubectl apply -f -


		## Install an implementation

		Service APIs is a set of specification that multiple implementations confirm to.


		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.

		Service APIs is a collection of Kubernetes Custom Resource Definitions that need
		to be installed into any Kubernetes cluster.

		- An `acme-lb` GatewayClass which is being managed by a `acme.io/gateway-controller`
		controller running in the cluster.

	With this configuration, you now have a Gateway reource which is forwarding
	With this configuration, you now have a Gateway resource which is forwarding

write a very simple getting started guide #427

write a very simple getting started guide #427

Conversation

hbagdi commented Oct 27, 2020

Note

robscott left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hbagdi commented Oct 28, 2020

hbagdi commented Oct 28, 2020

hbagdi commented Oct 28, 2020

robscott commented Oct 28, 2020

hbagdi commented Oct 29, 2020

robscott left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hbagdi commented Nov 2, 2020

robscott left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youngnick left a comment

Choose a reason for hiding this comment

hbagdi commented Nov 5, 2020

robscott commented Nov 5, 2020

k8s-ci-robot commented Nov 5, 2020

robscott left a comment •

edited

Loading