fix: rename k8s ingress controller to k8s operator

[russorat]

also includes some broken link fixes and server-addr to connect_url changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
ngrok-docs	✅ Ready (Inspect)	Visit Preview	Sep 23, 2024 6:11pm

[hjkatz]

Notes (for this PR):

• I think these are missing wording like "ngrok Kubernetes Operator" or ngrok-operator or "the operator" (lowercase)

  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/getting-started-kic/#:~:text=within%20the%20Kubernetes%20Operator%20allows
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/getting-started-gwapi/#:~:text=usage%20of%20the%20Kubernetes%20Operator
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/user-guide/#:~:text=currently%20only%20supported-,with%20the%20Operator.,-ngrok%20offers%20the
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/deployment-guide/#:~:text=install%20the%20operator.
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/deployment-guide/#:~:text=container%20is%20available%20on%20Docker%20Hub%20at%20ngrok/ingress%2Dcontroller%20and%20can%20be
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=options%20for%20the%20operator.
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=capability%20only%20applies-,to%20the%20Operator,-The%20Ngrok%20Kubernetes
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=By%20default%2C%20the%20Operator%20watches%20all%20namespaces.
    • Might be worth just rewording this paragraph: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#watching-specific-namespaces
  • https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/crds/#:~:text=precaution%2C%20the%20Operator%20does%20NOT%20delete

• Overview says "Kubernetes Ingress": https://www.forbes.com/sites/kateoflahertyuk/2024/07/04/authy-warns-33-million-users-update-your-ios-or-android-app-now/

  • I think this is more or less correct tbh. Up to you if we want to reword this at all.

• See: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/#:~:text=If%20you%20are%20running%20Kubernetes%20and%20do%20not%20want%20to%20use%20the%20ngrok%20SDKs%2C%20we%20recommend%20using%20the%20Operator

  • Can we reword this to "[...], we recommend using the ngrok-operator" linked to the github repo?

• https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/how-it-works/#:~:text=When%20someone%20hits%20the%20public%20endpoint%2C%20that%20traffic%20is%20sent%20down%20to%20the%20ngrok%20Kubernetes%20Operator%20and%20is%20forwarded%20to%20the%20services%20in%20the%20cluster.

  • Where is the ngrok-operator in this diagram? This might be out-of-scope for this PR.
  • 

• See: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/with-edges/#:~:text=While%20not%20implemented%20yet%2C%20when%20completed%2C%20this%20style%20of%20ingress%20should%20allow%20exposing%20a%20service%20across%20all%20edges%20configured%20by%20the%20controller.

  • Is this not yet implemented? I thought we do have this capability in k8s-op

• Missing quotation formatting: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/with-edges/#:~:text=If%20you%20create%20an%20Ingress%20resource%20without%20any%20hosts%20defined%20in%20the%20rules%2C%20then%20any%20web%20traffic%20to%20the%20IP%20address%20of%20your%20Ingress%20controller%20can%20be%20matched%20without%20a%20name%20based%20virtual%20host%20being%20required.

• We can use "routable" as a word here, see: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/with-edges/#:~:text=otherwise%20it%27s%20not-,route%2Dable,-.%20If%20a%20rule

• Install docs are not quite right: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/getting-started-kic/#:~:text=Install%20the%20ngrok%20Kubernetes%20Operator%3A

  • I think this is because we've not yet released the first version of ngrok/ngrok-operator, so it may be alright to leave this for now. But I still think that users may be confused why it says ngrok-ingress-controller, perhaps we should update the install to say:
  • $ helm install ngrok-operator ngrok/kubernetes-ingress-controller?
  • Same here: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/getting-started-gwapi/#:~:text=Install%20the%20ngrok%20Kubernetes%20Operator%3A

• I don't understand this sentence or its purpose: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/user-guide/#:~:text=For%20see%20or%20contribute%20a%20specific%20example%2C%20file%20a%20PR%20in%20the%20examples%20section%20of%20our%20repo%20see.

• https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/deployment-guide/#:~:text=This%20guide%20is%20meant%20as%20the%20starting%20point%20for%20configuring%2C%20deploying%2C%20and%20operating%20the%20controller%20component%20itself.%20It%20focuses%20on%20configurations%20and%20settings%20for%20the%20whole%20controller%2C%20and%20thus%20its%20corresponding%20ingress%20class%2C%20rather%20than%20individual%20ingress%20resources%20and%20their%20annotations.

  • Rewording of this paragraph is needed
  • We should also add links and code-formatting to "Helm" such as Helm
  • Is this dockerhub link still correct? I think we want https://hub.docker.com/r/ngrok/ngrok-operator instead

• Tabs in this section need a reword wrt enabled features: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/deployment-guide/?k8s-basic=gatewayAPI#installation

  • 
  • I have a (PR)[https://github.com/Namespace Helm Values by Feature Set ngrok-operator#442] that enables these feature sets via --set ingress.enabled=true and --set gateway.enabled=true

• https://dashboard.ngrok.com/get-started/setup/kubernetes

  • These docs need updating too: charts.ngrok.com, "ngrok-operator", Learn More links

• Whoops, we need to update these templates: https://github.com/ngrok/ngrok-operator/issues/new/choose

  • I'll do this one 😄 (https://github.com/ngrok-private/ngrok/issues/33390)

• Installation steps need updating: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=helm%20install%20my%2Dingress%2Dcontroller%20ngrok/kubernetes%2Dingress%2Dcontroller

• https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=to%20the%20Operator-,The%20Ngrok%20Kubernetes%20Operator,-supports%20the%20Kubernetes

  • This one is capitalized the other way around! 😂
  • Same here: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=By%20default%2C-,the%20Ngrok%20Kubernetes%20Operator,-creates%20a%20non

• Capitalization is all over the place here: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=which%20allows%20you%20to%20run%20multiple%20Operators%20in%20the%20same%20cluster.%20This%20feature%20is%20useful%20if%20you%20want%20to%20run%20multiple%20versions%20of%20the%20Ngrok%20Kubernetes%20Operator%20or%20other%20Operators%20in%20the%20same%20cluster.

  • I think there's a difference between "an operator" and "the ngrok Kubernetes Operator", etc...

• Needs rewording: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=Operators%20work%20by%20watching%20Kubernetes

  • I think in this case we actually want to say "ngrok Ingress Controller", etc...

• hmmm, I need to update these docs too it seems: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=You%20can%20override%20this%20name%20via%20the%20helm%20value%20ingressClass.name%2C%20or%20if%20there%20aren%27t%20other%20Operators%20in%20the%20cluster%2C%20you%20can%20set%20it%20to%20default%20to%20be%20true%20and%20not%20have%20to%20add%20the%20ingressClass%20to%20the%20ingress%20objects%27%20specs.

  • See PR: Namespace Helm Values by Feature Set ngrok-operator#442
  • Perhaps we should chat about how best to keep these docs up-to-date with changes?

• Missing callout banner for "warning": https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/crds/#:~:text=ngrok%20Kubernetes%20Operator.-,Warning%3A%20There,-are%20other%20CRDs

• Is this a hidden page? https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/developer-guide/internal-crds/

  • I think this page needs an update for the wording more generally.

• Rename to "operator": https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/crds/#:~:text=Domains%20are%20automatically-,created%20by%20the%20controller%20based%20on%20the%20ingress,-objects%20host%20values

• Different capitalization: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/custom-domain/#:~:text=If%20you%20create%20an%20ingress%20object%20(k8s%20ingress)%20or%20route%20object%20(Gateway%20API)

Overall Docs Notes (not for this PR):

• Is this order correct?
  • 
  • I think the "Getting Started" pages should be first with "Connecting to Edges" later on?
• The capatilaziton in our docs is kinda all over the place. I recommend we review for a standard of sorts. Here are some common cases I found:
  • "ngrok", at beginning, middle, end of sentence. as an adjective, etc...
  • How to refer to APIs or Products (capitalized?)
  • How to refer to Kubernetes resources (which casing? "pods" or "Pods" or "kind: Pod" etc...?)
  • Ex. "This ngrok Kubernetes Operator automatically creates and manages ngrok Edges based on the Kubernetes objects you create."
    • Why is "Kubernetes" more important than "ngrok" for example? Or Edges more than "ngrok"?
  • Ex. "Rules spread across kubernetes objects with matching hosts get merged into the same ngrok Edge"
    • here we do not capitalize "kubernetes", but in other cases we do
  • Ex. https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/user-guide/#:~:text=These%20modules%20are%20currently%20only%20supported%20with%20the%20ingress%20controller.%20The%20Gateway%20API%20supports%20some%20of%20these%20capabilities%20using%20route%20rules
    • Why "ingress controller" but "Gateway API"?
  • Ex. https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/deployment-guide/#:~:text=helm%20%2D%203.0.0%20or%20later.
    • Why "helm" but "Kubernetes"?
  • Ex. https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/advanced-deployments/#:~:text=If%20you%27re%20facing%20such%20issues%2C%20you%20can%20run%20the%20ngrok%20cli%20command%2C
    • Why "cli" but "API"?
• While reading the docs I ran across some comma splices. This made it difficult to read/understand the sentences' purposes.
  • Ex. https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/with-edges/#:~:text=If%20a%20rule%20with%20no%20host%20is%20created%2C%20it%20will%20be%20dropped.
  • Ex. https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/deployment-guide/?k8s-basic=ingress#installation:~:text=These%20credentials%20will%20be%20created%20as%20a%20Kubernetes%20secret%2C%20which%20the%20controller%20will%20have%20access%20to.
• K8s resource names can be plural too, so https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/user-guide/#:~:text=s%20are%20designed%20to%20be%20composable
  • doesn't need to be NgrokModuleSets, and can instead be NgrokModuleSets just fine
  • This should help with readibility too
  • See: https://github.com/ngrok/ngrok-operator/blob/main/helm/ngrok-operator/templates/crds/ingress.k8s.ngrok.com_ngrokmodulesets.yaml#L8-L14
• Should be a warning: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/user-guide/#:~:text=%2Dport%3E-,NOTE,-Using%20both%20an

Other Questions (for k8s-bindings project more generally):

• re: https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/getting-started-gwapi/#:~:text=Install%20the%20GatewayClass%20object%3A
  • Should we install this for users the same we do for ingressClass? See: https://github.com/ngrok/ngrok-operator/blob/main/e2e-fixtures/ingress-class/ingress-class.yaml
• Is this CRDs page auto-generated? https://ngrok-docs-git-ror-k8s-update-ngrok-dev.vercel.app/docs/k8s/crds/
  • Should it be?