docs: expand Divert setup, shared environments, and troubleshooting - #1155
docs: expand Divert setup, shared environments, and troubleshooting#1155codyjlandstrom wants to merge 5 commits into
Conversation
✅ Deploy Preview for okteto-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for okteto-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Document Linkerd as optional for the nginx driver: ingress-level routing works without it, Linkerd extends routing to service-to-service calls. The original draft said it was required. - Remove the divert.debug manifest field and the api.logLevel Helm value; neither exists in the CLI schema or the chart. - Replace the step-by-step getting started section with a role-based setup path that links to the detailed guides instead of repeating their content. - Split troubleshooting by audience: developer issues in Using Divert, admin issues in Configure Divert. The core page links to both. - Keep everything that landed on main after this branch was opened: the Istio installation guide, the ingress controller architecture section, the okteto-community sample URLs, and the virtualServices/hosts field docs. - Drop the versioned_docs/version-1.40 copies; 1.47 is current and new content targets src/content only. - Style pass per STYLE_GUIDE.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Cody Landstrom <cody@okteto.com>
codyjlandstrom
changed the title
| linkerd viz check | ||
| ``` | ||
|
|
||
| ## Configure Okteto for Linkerd |
There was a problem hiding this comment.
There is some other configuration missed. Some changes in the okteto-nginx has to change, and a feature has to be enabled. Please, check the notion document, all the config changes needed are there
| namespace: | ||
| annotations: | ||
| linkerd.io/inject: enabled |
There was a problem hiding this comment.
This is not correct. Adding this would imply that every namespace within Okteto would have the sidecard injection, but this is only needed in the shared environments, not in the rest of cases
|
|
||
| :::info | ||
| Linkerd is **optional** for the nginx driver. The basic Divert functionality works without it, but Linkerd enables enhanced service-to-service routing within the mesh. | ||
| Linkerd is **optional** for the nginx driver. Without Linkerd, Divert routes traffic at the ingress level. Installing Linkerd extends header-based routing to service-to-service calls inside the cluster. |
There was a problem hiding this comment.
I'm not sure we should promote the usage of the nginx driver without Linkerd. it is easy that at some point some scenario where service-to-service communication is needed, and stops working, and people might think that Divert is not working fine
| helm upgrade okteto okteto/okteto -f values.yaml | ||
| ``` | ||
|
|
||
| ### Existing Namespaces |
There was a problem hiding this comment.
Maybe it is important to highlight that this is only needed for shared environments. The rest of namespace doesn't require to do this
| 3. **Load balancing**: Intelligent load balancing across service instances | ||
| 3. **Load balancing**: Latency-aware load balancing across service instances | ||
| 4. **mTLS**: Automatic mutual TLS between services for enhanced security | ||
| 5. **Observability**: Detailed metrics and tracing for diverted traffic (visible to administrators) |
There was a problem hiding this comment.
I wouldn't mention this for now, we didn't do any check on what is visible or not, and how they could be integrated with Okteto.
My fear is that if we mention this, people might expect having those metrics accessible somewhere, and right now is not possible
| // Using Spring's WebClient | ||
| webClient.get() | ||
| .uri("http://catalog-service/api/movies") | ||
| .header("baggage", baggage) | ||
| .retrieve(); |
There was a problem hiding this comment.
In this sample we are missing how to extract the value of the baggage header
|
|
||
| 1. Deploys only the services defined in your manifest | ||
| 2. Configures routing to redirect requests for missing services to the shared namespace | ||
| 3. Injects the `baggage: okteto-divert=<your-namespace>` header into requests through your endpoints |
There was a problem hiding this comment.
It is important to mention that the header is automatically injected in the endpoints for the diverted/user's namespace.
It is also important to mention here that any public endpoint from the staging environment is also generated for the diverted/user's namespace. I mean, we don't only generate the endpoints for the services deployed, we also generate different ones for the services not deployed (if they are generated in the shared namespace)
| okteto deploy -f okteto.frontend.yaml | ||
| ``` | ||
|
|
||
| ## Header Propagation |
There was a problem hiding this comment.
Already mentioned in the general divert page, but it might also fit here. We can mention that there are libraries in a lot of programming languages as we use baggage header which is commonly used to propagate context or tracing information between services
| if (targetNamespace === CURRENT_NAMESPACE || targetNamespace === 'shared') { | ||
| // Process this message | ||
| await processOrder(JSON.parse(message.Body)); | ||
| } | ||
| } |
There was a problem hiding this comment.
We might refer to OKTETO_DIVERTED_NAMESPACE env var, as we are injecting it into diverted namespaces to be used to consume the expected messages. Some of our samples use this pattern, you can check them
| } | ||
| ``` | ||
|
|
||
| ### Kafka Topic Routing |
There was a problem hiding this comment.
To use this the kafka consumer has to be configured to use Consumer Groups, it might be relevant to mention it here to avoid misunderstandings. If not, this pattern wouldn't work fine
2 participants
Expands the Divert docs based on the feedback from the initial release, and reconciles the branch with everything that landed on main since February.
What this adds
core/divert.mdx): prerequisites by role, driver configuration, shared environment creation, manifest configuration, and verification. Each step links to the detailed guide instead of repeating it.Corrections from the original draft
divert.debugmanifest field that does not exist in the CLI schema.api.logLevelHelm value that does not exist in the chart.versioned_docs/version-1.40copies. 1.47 is current, so this content targetssrc/content/only.Merge with main
Merged main and kept everything that landed since this branch was opened: the Istio installation guide (#1177), the ingress controllers architecture section (#1187), the
okteto-communitysample repo URLs (#1178, #1196), and thevirtualServices/hostsfield documentation (#1197). Also fixed two pre-existing broken relative links in the Configure Divert "Next Steps" section.Style pass done per
STYLE_GUIDE.md.yarn buildpasses.🤖 Generated with Claude Code