Docs: Can't find docs on how to create cluster internal-only Knative service

[ahmetb]

I searched for:

• internal only knative app
• knative services without external endpoint
• knative do not expose

but didn't land anywhere in the docs repo explaining how this can be done. Are we lacking docs on this topic?

/kind bug
/area serving
/area networking

[tcnghia]

We have some docs in https://github.com/knative/docs/blob/master/serving/cluster-local-route.md, but it is evident from this bug that we should make it more visible.

[ahmetb]

@tcnghia yeah the wording is not great in that doc.

The fact that "making routes local to your cluster" is means to an end. Users are interested in the "end" part of it, which is "how do I do X".

[ahmetb]

Let's try to fix this. Other people hit this just asking me where can I find docs about how to create internal/external services on Knative.

[abrennan89]

Hey folks. I went to look into this issue and maybe assign it to myself, but it looks like it could be covered now at https://knative.dev/docs/serving/cluster-local-route/ ?

[abrennan89]

Maybe there is scope here instead to have a top level section on "Configuring access for Knative Services" and then break this down into internal and external access, defaults, etc, so that it provides better context for users?

[abrennan89]

/assign abrennan89

@samodell assigning this to myself to work on if that's OK :slightly_smiling_face: lmk what you think / if there are any issues with this. Thanks!

[samodell]

Hey @abrennan89 , go for it! I think the main problem is discoverability; we have a lot of the info, but it's called out in a confusing way. "Cluster local route" isn't what folks think of when they're thinking about creating an internal-only or private service, but that's what the main page that talks about this is called.

[RichieEscarez]

This topic about internal k8s services also exists and is related: https://knative.dev/docs/serving/knative-kubernetes-services/

We should tie these topics together into a thorough overview and then nest the related "task" topics under that overview (how to do X (and WHY)). See Proposed navigation structure here

Thank you @ahmetb and @abrennan89 for surfacing this issue (or content gap) and taking it on!

[ahmetb]

This topic about internal k8s services also exists and is related: knative.dev/docs/serving/knative-kubernetes-services

this seems to be a misunderstanding. we're not talking about Kubernetes Services that are created as part of Knative installation; we're talking about Knative Services created by users (which aren't explained in this linked doc, or anywhere else).

[RichieEscarez]

I agree but I'm in the middle of trying to organize our library to align with the developer flow and was simply trying to group "services" into a single section. Within that section, we can have separate topics or even another section specific about knative services.

That said, would it be incorrect or confusing to group all 'services' related content? Do they fall under different roles? (Is Operator vs developer)

[ahmetb]

Any k8s core/v1 Service that appears under knative-serving namespace has nothing to do with any user-created Knative Service. So it doesn't make sense they're in the same doc.

TBH https://knative.dev/docs/serving/knative-kubernetes-services/ this doc is a deep dive that most knative users don't even need to know. It's an explanation of knative internal machinery. Most users won't change these, so I would not make this article prominent.

[RichieEscarez]

Thanks @ahmetb! I'd love to get more of this level of feedback in our Nav proposal.

[abrennan89]

This topic about internal k8s services also exists and is related: knative.dev/docs/serving/knative-kubernetes-services

this seems to be a misunderstanding. we're not talking about Kubernetes Services that are created as part of Knative installation; we're talking about Knative Services created by users (which aren't explained in this linked doc, or anywhere else).

@RichieEscarez I'm a little unclear about what we want to document now. Should we separate the Knative Services stuff we were talking about into another ticket since it's two different types of services? Getting the feeling this issue still needs its own new section of content re user created services?

@markusthoemmes can you or do you know who can provide information about creating cluster internal-only Knative Services when they're user created services as opposed to Kubernetes Services that are created as part of Knative installation? Or any user created services info period I guess if we're able to document this yet?

[RichieEscarez]

Sorry about that, I should have also made mention of the changes I pushed into the Nav proposal.

@RichieEscarez I'm a little unclear about what we want to document now. Should we separate the Knative Services stuff we were talking about into another ticket since it's two different types of services?

Our outline for what we want and what's missing is all being tracked in the Nav proposal, so I've updated is per ahmetb's input. Ultimately we are restructuring all the content into "task-oriented information" so Ive added comments about what we'd like to change in that document.

Getting the feeling this issue still needs its own new section of content re user created services?

Given that some things have changed, including the fact that "Services are externally accessible by default" (re: https://github.com/knative/docs/issues/1859):

I think we whats missing is a the task and reference information about how to "create a Knative service". Then at the end of that (since that service is external by default), you can point to (or better yet, add as a sub-section) that covers the task of "configuring a service as an internal cluster only service". (see Nav proposal for more comments).

The Serving spec is in the repo now, from which you can use to author the

• https://github.com/knative/docs/blob/release-0.10/docs/serving/spec/knative-api-specification-1.0.md#service

• https://github.com/knative/docs/blob/release-0.10/docs/serving/spec/knative-api-specification-1.0.md#service-1

• https://github.com/knative/docs/blob/release-0.10/docs/serving/spec/knative-api-specification-1.0.md#service-2

Just responding here for clarity about whats missing and what would solve this issue but we can meet and chat more (or use the Docs WG meeting if you like)?

Thanks for taking this on @abrennan89 !

[knative-housekeeping-robot]

Issues go stale after 90 days of inactivity.
Mark the issue as fresh by adding the comment /remove-lifecycle stale.
Stale issues rot after an additional 30 days of inactivity and eventually close.
If this issue is safe to close now please do so by adding the comment /close.

Send feedback to Knative Productivity Slack channel or file an issue in knative/test-infra.

/lifecycle stale

[ahmetb]

/lifecycle frozen
I am not sure if it’s fixed yet. Pls close if it is.

[abrennan89]

Sorry @ahmetb - the PRs related to this that I had attempted to work on got pretty confusing pretty fast, so I ended up closing them.
I think this needs to be worked on as part of a bigger problem of re-organizing a bunch of our documentation so that it's easier to find what folks are looking for.

I think we're planning to meet soon in the docs WG to iron out the information architecture work that's required here. Hopefully I'll get back to this soon.

Thanks for your patience.