You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
New page. Moves a self-managed Istio sidecar mesh to the Calico-managed Ambient Mode mesh, one namespace at a time.
Three commits:
Phil DiCorpo's draft, exactly as attached to DOCS-3037.
Sidebar entry under Security > Istio Ambient Mode.
HTML comments changed to MDX comment syntax. <!-- --> is a syntax error in MDX v3, and it broke the whole site build.
Five ENG REVIEW notes are still in the source and still unanswered. The one in "Plan your cutover" is a blocker. The page's stated reason for the no-coexistence rule does not match the operator code. I will post the detail inline.
Not in scope
calico-cloud and calico. The page applies there too. Separate PR once the content settles.
Test plan
BUILD_NEXT=true yarn build passes. onBrokenLinks: 'throw' and no broken links.
Page checked in a local dev build. Sidebar, tables, admonitions and $[prodname] all render right.
Deploy preview inspected.
Added a topic for migrating from an Istio sidecar mesh to Istio Ambient Mode.
AI assistance: This PR was written in part with the assistance of generative AI.
Phil's draft from DOCS-3037, attachment 39169, committed as attached.
Open ENG REVIEW comments stay in the file for now.
Co-authored-by: Phil DiCorpo <phil@tigera.io>
Docusaurus 3 compiles these pages as MDX v3, where an HTML comment is a
syntax error. The five notes broke the MDX build, and one broken file
fails the whole site compile.
Content is unchanged. The notes stay invisible in the rendered page.
1 paths audited Performance: 76 (🔴 down 22 from production) Accessibility: 98 (no change from production) Best Practices: 92 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports
The guard checks only the Gateway CRD. A cluster can already have that CRD while lacking GatewayClass or HTTPRoute, causing this command to skip installation and later waypoint apply or route creation to fail.
The 24-hour window is presented as the planning limit even though the review note acknowledges it is only Istio's default and has not been tested by Tigera. Certificate lifetime is configurable, so customers may either run out sooner or unnecessarily rush the migration. Verify the bundled configuration/tested lifetime or instruct users to check the actual certificate expiry and provide a supported renewal or rollback path.
* **Certificates are not rotated.** After the self-managed istiod is gone, sidecars can no longer refresh their workload certificates. Istio's default certificate lifetime is 24 hours, so plan to finish the migration well inside that window.
Only Deployments are restarted here, so StatefulSets, DaemonSets, and standalone pods in the namespace retain their sidecars. The page then treats the namespace as migrated and validates it, leaving those workloads outside ambient mode. Restart every supported workload controller and explicitly handle standalone pods before declaring the namespace migrated.
1. **Restart the workloads** to drop the sidecars:
```bash
kubectl rollout restart deployment -n <namespace>
kubectl rollout status deployment -n <namespace>
The rollback only removes the namespace label, but the procedure also supports attaching a Waypoint to an individual Service. In that case the service-level istio.io/use-waypoint label remains and traffic is still attached after rollback. Remove the label from the namespace and every service that was labeled.
--purge removes the Istio CRDs, which cascades deletion of the VirtualService, AuthorizationPolicy, DestinationRule, and other custom resources that Steps 3–4 later ask the user to inspect, replace, or retain. The procedure therefore loses the live policy objects before migration and cannot preserve L4 policies as stated; use a component-only uninstall that retains them, or explicitly recreate the backup after the managed CRDs are installed before continuing.
1. Uninstall the self-managed control plane, including the Istio CNI plugin:
```bash
istioctl uninstall --purge
**calico-enterprise/compliance/istio/migrate-from-sidecar.mdx:320**
* Deleting every selector-based policy that contains an L7 rule also deletes any L4 rules in the same policy. zTunnel can enforce those L4 rules, so a mixed policy must be split and its L4 portion retained rather than removed wholesale.
Delete the selector-based policies that contain Layer 7 rules, which you have already replaced with Waypoint-targeted equivalents:
This is not true for the phased path: removing the self-managed control plane removes or changes the injector used by namespaces that still have sidecar-injection labels. New or restarted pods in those namespaces will not remain equivalent to the old mesh, even though they are not yet labeled ambient. Call out that they must be frozen or provide a tested coexistence/transition mechanism.
Repeat for each namespace. Namespaces you have not labeled are unaffected, subject to the certificate and mTLS constraints described in [Pattern 2](#pattern-2-phased-namespace-by-namespace).
* Connect-time load balancing is not compatible with Istio Ambient Mode.
* Destination ports are preserved only when Istio is deployed without Waypoint. If you deploy Waypoint, traffic through the Waypoint shows port 15008 as its destination port.
{/* ENG REVIEW: confirm eBPF dataplane + ambient status for the shipping version. Fixes for the host-probe/SNAT issue landed in projectcalico/calico#9159 and #9192; confirm whether eBPF mode is a supported configuration for the bundled Istio, and whether Waypoint on eBPF is supported (see istio/istio#55481). If it is not, it belongs in this list. */}
Skip this step if all of your `AuthorizationPolicy` resources are Layer 4 only and you do not use `VirtualService` for routing, retries, fault injection, or header manipulation.
The Tigera Operator installs istiod, the Istio CNI plugin, and zTunnel into the `calico-system` namespace.
It cannot run alongside a self-managed Istio control plane.
Both installations use a validating webhook named `istiod-default-validator`, both add an Istio CNI plugin to the same CNI configuration on every node, and both control planes manage the same built-in `GatewayClass` resources.
| Sidecar injection removed | Re-add the label you recorded in [Inventory your mesh](#inventory-your-mesh): `kubectl label namespace <namespace> istio-injection=enabled`, or `kubectl label namespace <namespace> istio.io/rev=<revision>` |
| Workloads restarted | Re-add the injection label, then `kubectl rollout restart deployment -n <namespace>` |
| Old policies deleted | `kubectl apply -f istio-config-backup.yaml` |
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🟡 Changes recommended
The migration procedure contains unresolved policy, workload, namespace, rollback, and resource-handling issues, including a critical risk of deleting L4 enforcement.
Get a fresh assessment by requesting another Copilot review.
This justification does not match the operator implementation closely enough to support a destructive uninstall. The managed renderer is a calico-istio release in calico-system, and its expected resources include both istiod-default-validator and a separate istio-validator-calico-system; the operator code does not establish that the sidecar and managed installations both own the same GatewayClass resources. Replace this with the exact, tested conflicts (for example, the shared webhook/CNI resources) and the version scope before making this mandatory.
Commands assume an incorrect fixed mesh root namespace
This assumes every self-managed installation uses istio-system as its root namespace, but the supported starting point does not impose that constraint. With a customized meshConfig.rootNamespace (or a revision using another control-plane namespace), the commands below inspect the wrong namespace and mesh-wide policies remain outside the managed root, changing enforcement after Step 2. Resolve the configured root namespace first and use it in the commands, or explicitly narrow the supported starting point.
Skip condition omits Waypoint-required authentication and traffic policies
This skip condition omits two features that the table above says require a Waypoint: RequestAuthentication must target a Waypoint, and DestinationRule traffic policies are applied by the Waypoint. A user with either can therefore skip Step 3 and silently lose JWT authentication or traffic-policy behavior after the sidecars are removed. Include those cases in the condition or provide a separate migration path.
Restart misses StatefulSets, DaemonSets, and standalone pods
This restart covers only Deployments, but the supported starting point is not limited to Deployment workloads. StatefulSets, DaemonSets, and other workload controllers can retain their injected sidecars, so the namespace may be advanced while those pods are still running in sidecar mode. Enumerate the relevant workload types (and handle standalone pods where applicable) before declaring the namespace migrated.
Delete the selector-based policies that contain Layer 7 rules, which you have already replaced with Waypoint-targeted equivalents:
This file contains hidden or 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
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.
Product Version(s):
Calico Enterprise, next / unreleased.
Issue:
Link to docs preview:
/calico-enterprise/next/compliance/istio/migrate-from-sidecarSummary
New page. Moves a self-managed Istio sidecar mesh to the Calico-managed Ambient Mode mesh, one namespace at a time.
Three commits:
<!-- -->is a syntax error in MDX v3, and it broke the whole site build.Five
ENG REVIEWnotes are still in the source and still unanswered. The one in "Plan your cutover" is a blocker. The page's stated reason for the no-coexistence rule does not match the operator code. I will post the detail inline.Not in scope
calico-cloudandcalico. The page applies there too. Separate PR once the content settles.Test plan
BUILD_NEXT=true yarn buildpasses.onBrokenLinks: 'throw'and no broken links.$[prodname]all render right.AI assistance: This PR was written in part with the assistance of generative AI.