diff --git a/docs/FAQ.md b/docs/FAQ.md index caa9df475f..2986eceb0a 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,6 +1,6 @@ # FAQ -Be sure to read the [Best practices page](../best-practices) as well. +Be sure to read the [Best practices page](best-practices) as well. ## General diff --git a/docs/analysis/prometheus.md b/docs/analysis/prometheus.md index 0fb2fb6a65..f3618c7237 100644 --- a/docs/analysis/prometheus.md +++ b/docs/analysis/prometheus.md @@ -37,7 +37,7 @@ spec: The example shows Istio metrics, but you can use any kind of metric available to your prometheus instance. We suggest you validate your [PromQL expression](https://prometheus.io/docs/prometheus/latest/querying/basics/) using the [Prometheus GUI first](https://prometheus.io/docs/introduction/first_steps/#using-the-expression-browser). -See the [Analysis Overview page](../../features/analysis) for more details on the available options. +See the [Analysis Overview page](../features/analysis) for more details on the available options. ## Range queries diff --git a/docs/architecture.md b/docs/architecture.md index e5640c025b..ddfa033b28 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,16 +12,16 @@ will read all the details of the rollout and bring the cluster to the same state Note that Argo Rollouts will not tamper with or respond to any changes that happen on normal [Deployment Resources](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). This means that you can install Argo Rollouts in a cluster that is also deploying applications with alternative methods. -To install the controller in your cluster and get started with Progressive Delivery, see the [Installation page](../installation/). +To install the controller in your cluster and get started with Progressive Delivery, see the [Installation page](installation). ## Rollout resource The Rollout resource is a custom Kubernetes resource introduced and managed by Argo Rollouts. It is mostly compatible with the native Kubernetes Deployment resource but with extra fields that control the stages, thresholds and methods of advanced deployment methods such as canaries and blue/green deployments. -Note that the Argo Rollouts controller will only respond to those changes that happen in Rollout sources. It will do nothing for normal deployment resources. This means that you need to [migrate your Deployments to Rollouts](../migrating/) if you want to manage them with Argo Rollouts. +Note that the Argo Rollouts controller will only respond to those changes that happen in Rollout sources. It will do nothing for normal deployment resources. This means that you need to [migrate your Deployments to Rollouts](migrating) if you want to manage them with Argo Rollouts. -You can see all possible options of a Rollout in the [full specification page](../features/specification/). +You can see all possible options of a Rollout in the [full specification page](features/specification). ## Replica sets for old and new version @@ -34,7 +34,7 @@ Note also that the replica sets that take part in a Rollout are fully managed by This is the mechanism that traffic from live users enters your cluster and is redirected to the appropriate version. Argo Rollouts use the [standard Kubernetes service resource](https://kubernetes.io/docs/concepts/services-networking/service/), but with some extra metadata needed for management. Argo Rollouts is very flexible on networking options. First of all you can have different services during a Rollout, that go only to the new version, only to the old version or both. -Specifically for Canary deployments, Argo Rollouts supports several [service mesh and ingress solutions](../features/traffic-management/) for splitting traffic with specific percentages instead of simple balancing based on pod counts and it is possible to use multiple routing providers simultaneously. +Specifically for Canary deployments, Argo Rollouts supports several [service mesh and ingress solutions](features/traffic-management) for splitting traffic with specific percentages instead of simple balancing based on pod counts and it is possible to use multiple routing providers simultaneously. ## AnalysisTemplate and AnalysisRun @@ -46,14 +46,14 @@ For performing an analysis, Argo Rollouts includes two custom Kubernetes resourc Note that using an analysis and metrics in a Rollout is completely optional. You can manually pause and promote a rollout or use other external methods (e.g. smoke tests) via the API or the CLI. You don't need a metric solution just to use Argo Rollouts. You can also mix both automated (i.e. analysis based) and manual steps in a Rollout. -Apart from metrics, you can also decide the success of a rollout by running a [Kubernetes job](../analysis/job/) or running [a webhook](../analysis/web/). +Apart from metrics, you can also decide the success of a rollout by running a [Kubernetes job](analysis/job) or running [a webhook](analysis/web). ## Metric providers -Argo Rollouts includes [native integration for several popular metrics providers](../features/analysis/) that you can use in the Analysis resources to automatically promote or rollback a rollout. See the documentation of each provider for specific setup options. +Argo Rollouts includes [native integration for several popular metrics providers](features/analysis) that you can use in the Analysis resources to automatically promote or rollback a rollout. See the documentation of each provider for specific setup options. ## CLI and UI (Not shown in the diagram) -You can view and manage Rollouts with the [Argo Rollouts CLI](../features/kubectl-plugin/) or the [integrated UI](../dashboard/). Both are optional. +You can view and manage Rollouts with the [Argo Rollouts CLI](features/kubectl-plugin) or the [integrated UI](dashboard). Both are optional. diff --git a/docs/best-practices.md b/docs/best-practices.md index 0ed32efbec..096d953b9f 100644 --- a/docs/best-practices.md +++ b/docs/best-practices.md @@ -1,6 +1,6 @@ # Best Practices -This document describes some best practices, tips and tricks when using Argo Rollouts. Be sure to read the [FAQ page](../FAQ) as well. +This document describes some best practices, tips and tricks when using Argo Rollouts. Be sure to read the [FAQ page](FAQ) as well. ## Check application compatibility @@ -23,7 +23,7 @@ Note also that Argo Rollouts is a self-contained solution. It doesn't need Argo ## Understand your use case -Argo Rollouts is perfect for all progressive delivery scenarios as explained in [the concepts page](../concepts). +Argo Rollouts is perfect for all progressive delivery scenarios as explained in [the concepts page](concepts). You should *NOT* use Argo Rollouts for preview/ephemeral environments. For that use case check the [Argo CD Pull Request generator](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Generators-Pull-Request/). @@ -59,7 +59,7 @@ Ideally you should have proper metrics that tell you in 5-15 minutes if a deploy If you are doing a deployment right now and then have an actual human looking at logs/metrics/traces for the next 2 hours, adopting Argo Rollouts is not going to help you a lot with automated deployments. -Get your [metrics](../features/analysis) in place first and test them with dry-runs before applying them to production deployments. +Get your [metrics](features/analysis) in place first and test them with dry-runs before applying them to production deployments. ## There is no "Argo Rollouts API" @@ -72,14 +72,14 @@ But as explained in the previous point the end goal should be fully automated de There are two main ways to integrate other systems with Argo Rollouts. -The easiest way is to use [Notifications](../features/notifications). This means that when a rollout is finished/aborted you send a notification to another system that does other tasks that you want to happen. +The easiest way is to use [Notifications](features/notifications). This means that when a rollout is finished/aborted you send a notification to another system that does other tasks that you want to happen. Alternatively you can control Rollouts with the CLI or by patching manually the Kubernetes resources. ## Use the Kubernetes Downward API -If you want your applications to know if they are part of a canary or not, you can use [Ephemeral labels](../features/ephemeral-metadata) along with the [Kubernetes downward api](https://kubernetes.io/docs/concepts/workloads/pods/downward-api/). +If you want your applications to know if they are part of a canary or not, you can use [Ephemeral labels](features/ephemeral-metadata) along with the [Kubernetes downward api](https://kubernetes.io/docs/concepts/workloads/pods/downward-api/). This means that your application will read from files its configuration in a dynamic manner and adapt according to the situation. @@ -141,10 +141,10 @@ spec: service: name: guestbook-root port: - number: 443 + number: 443 ``` -The above technique has the a benefit in that it would not incur additional cost of allocating +The above technique has the benefit in that it would not incur additional cost of allocating additional load balancers. ## Reducing operator memory usage diff --git a/docs/features/canary/index.md b/docs/features/canary/index.md index d14967ae69..084ee8819b 100644 --- a/docs/features/canary/index.md +++ b/docs/features/canary/index.md @@ -10,7 +10,7 @@ There are multiple steps available, the most basic ones are `setWeight` and `pau !!! important - If the canary Rollout does not use [traffic management](traffic-management/index.md), the Rollout makes a best effort attempt to achieve the percentage listed in the last `setWeight` step between the new and old version. For example, if a Rollout has 10 Replicas and 10% for the first `setWeight` step, the controller will scale the new desired ReplicaSet to 1 replicas and the old stable ReplicaSet to 9. In the case where the setWeight is 41%, the Rollout attempts to get there by finding the whole number with the smallest delta, rounding up the calculation if the deltas are equals (i.e. the new ReplicaSet has 4 pods since 41% of 10 is closer to 4/10 than 5/10, and the old ReplicaSet has 6 pods). If a user wants to have more fine-grained control of the percentages without a large number of Replicas, that user should use the [traffic management](#trafficrouting) functionality. + If the canary Rollout does not use [traffic management](../traffic-management/index.md), the Rollout makes a best effort attempt to achieve the percentage listed in the last `setWeight` step between the new and old version. For example, if a Rollout has 10 Replicas and 10% for the first `setWeight` step, the controller will scale the new desired ReplicaSet to 1 replicas and the old stable ReplicaSet to 9. In the case where the setWeight is 41%, the Rollout attempts to get there by finding the whole number with the smallest delta, rounding up the calculation if the deltas are equals (i.e. the new ReplicaSet has 4 pods since 41% of 10 is closer to 4/10 than 5/10, and the old ReplicaSet has 6 pods). If a user wants to have more fine-grained control of the percentages without a large number of Replicas, that user should use the [traffic management](#trafficrouting) functionality. ## Example @@ -64,7 +64,7 @@ spec: - pause: {} # pause indefinitely ``` -If no `duration` is specified for a pause step, the rollout will be paused indefinitely. To unpause, use the [argo kubectl plugin](kubectl-plugin.md) `promote` command. +If no `duration` is specified for a pause step, the rollout will be paused indefinitely. To unpause, use the [argo kubectl plugin](../../features/kubectl-plugin) `promote` command. ```shell # promote to the next step @@ -196,13 +196,13 @@ spec: ### analysis -Configure the background [Analysis](analysis.md) to execute during the rollout. If the analysis is unsuccessful the rollout will be aborted. +Configure the background [Analysis](../analysis.md) to execute during the rollout. If the analysis is unsuccessful the rollout will be aborted. Defaults to nil ### antiAffinity -Check out the [Anti Affinity document](anti-affinity/anti-affinity.md) document for more information. +Check out the [Anti Affinity document](../anti-affinity/anti-affinity.md) document for more information. Defaults to nil @@ -232,6 +232,6 @@ Defaults to 25% ### trafficRouting -The [traffic management](traffic-management/index.md) rules to apply to control the flow of traffic between the active and canary versions. If not set, the default weighted pod replica based routing will be used. +The [traffic management](../traffic-management/index.md) rules to apply to control the flow of traffic between the active and canary versions. If not set, the default weighted pod replica based routing will be used. Defaults to nil diff --git a/docs/features/traffic-management/alb.md b/docs/features/traffic-management/alb.md index 5b4c424528..910110365b 100644 --- a/docs/features/traffic-management/alb.md +++ b/docs/features/traffic-management/alb.md @@ -149,7 +149,7 @@ spec: By default, a rollout will inject the `alb.ingress.kubernetes.io/actions.` annotation using the service/action name specified under `spec.strategy.canary.stableService`. However, it may be desirable to specify an explicit service/action name different from the `stableService`. For -example, [one pattern](/argo-rollouts/best-practices/#ingress-desiredstable-host-routes) is to use a single +example, [one pattern](../../best-practices#ingress-desiredstable-host-routes) is to use a single Ingress containing three different rules to reach the canary, stable, and root service separately (e.g. for testing purposes). In this case, you may want to specify a "root" service as the service/action name instead of stable. To do so, reference a service under `rootService` under the diff --git a/docs/features/traffic-management/google-cloud.md b/docs/features/traffic-management/google-cloud.md index 8f285ce9cf..489f6d6bbb 100644 --- a/docs/features/traffic-management/google-cloud.md +++ b/docs/features/traffic-management/google-cloud.md @@ -6,7 +6,7 @@ Useful resources: * [The Gateway API specification](https://gateway-api.sigs.k8s.io/) * [Support of the Gateway API in Google Cloud](https://cloud.google.com/kubernetes-engine/docs/concepts/gateway-api) -* [Argo Rollouts Plugin capabilities](../plugins/) +* [Argo Rollouts Plugin capabilities](plugins) * [Plugin for the Gateway API](https://github.com/argoproj-labs/rollouts-plugin-trafficrouter-gatewayapi) The process involves the following steps: diff --git a/docs/features/traffic-management/kong.md b/docs/features/traffic-management/kong.md index ad6e22bc84..2f892cb070 100644 --- a/docs/features/traffic-management/kong.md +++ b/docs/features/traffic-management/kong.md @@ -6,7 +6,7 @@ Useful resources: * [The Gateway API specification](https://gateway-api.sigs.k8s.io/) * [Support of the Gateway API in Kong](https://docs.konghq.com/kubernetes-ingress-controller/latest/concepts/gateway-api/) -* [Argo Rollouts Plugin capabilities](../plugins/) +* [Argo Rollouts Plugin capabilities](plugins) * [Plugin for the Gateway API](https://github.com/argoproj-labs/rollouts-plugin-trafficrouter-gatewayapi) The process involves the following steps: diff --git a/docs/getting-started/mixed/index.md b/docs/getting-started/mixed/index.md index 5c59f37098..759d38a3ae 100644 --- a/docs/getting-started/mixed/index.md +++ b/docs/getting-started/mixed/index.md @@ -9,7 +9,7 @@ This guide covers how Argo Rollouts integrates with multiple TrafficRoutings, us should be able to produce any other combination between the existing trafficRouting options. This guide builds upon the concepts of the [basic getting started guide](../../getting-started.md), -[NGINX Guide](getting-started/nginx/index.md), and [SMI Guide](getting-started/smi/index.md). +[NGINX Guide](../../getting-started/nginx/index.md), and [SMI Guide](../../getting-started/smi/index.md). ## Requirements - Kubernetes cluster with Linkerd installed diff --git a/docs/index.md b/docs/index.md index fa285746ca..3d04727f03 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ Argo Rollouts is a [Kubernetes controller](https://kubernetes.io/docs/concepts/a Argo Rollouts (optionally) integrates with [ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) and service meshes, leveraging their traffic shaping abilities to gradually shift traffic to the new version during an update. Additionally, Rollouts can query and interpret metrics from various providers to verify key KPIs and drive automated promotion or rollback during an update. -Here is a demonstration video (click to watch on Youtube): +Here is a demonstration video (click to watch on YouTube): [![Argo Rollouts Demo](https://img.youtube.com/vi/hIL0E2gLkf8/0.jpg)](https://youtu.be/hIL0E2gLkf8) @@ -44,9 +44,9 @@ Follow the full [getting started guide](getting-started.md) to walk through crea ## How does it work? Similar to the [deployment object](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), the Argo Rollouts controller will manage the creation, scaling, and deletion of [ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/). These ReplicaSets are defined by the `spec.template` field inside the Rollout resource, which uses the same pod template as the deployment object. -When the `spec.template` is changed, that signals to the Argo Rollouts controller that a new ReplicaSet will be introduced. The controller will use the strategy set within the `spec.strategy` field in order to determine how the rollout will progress from the old ReplicaSet to the new ReplicaSet. Once that new ReplicaSet is scaled up (and optionally passes an [Analysis](features/analysis/)), the controller will mark it as "stable". +When the `spec.template` is changed, that signals to the Argo Rollouts controller that a new ReplicaSet will be introduced. The controller will use the strategy set within the `spec.strategy` field in order to determine how the rollout will progress from the old ReplicaSet to the new ReplicaSet. Once that new ReplicaSet is scaled up (and optionally passes an [Analysis](features/analysis)), the controller will mark it as "stable". -If another change occurs in the `spec.template` during a transition from a stable ReplicaSet to a new ReplicaSet (i.e. you change the application version in the middle of a rollout), then the previously new ReplicaSet will be scaled down, and the controller will try to progress the ReplicasSet that reflects the updated `spec.template` field. There is more information on the behaviors of each strategy in the [spec](features/specification/) section. +If another change occurs in the `spec.template` during a transition from a stable ReplicaSet to a new ReplicaSet (i.e. you change the application version in the middle of a rollout), then the previously new ReplicaSet will be scaled down, and the controller will try to progress the ReplicasSet that reflects the updated `spec.template` field. There is more information on the behaviors of each strategy in the [spec](features/specification) section. ## Use cases of Argo Rollouts diff --git a/docs/migrating.md b/docs/migrating.md index 524b67444d..8ff3b984e3 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -11,7 +11,7 @@ When converting a Deployment to a Rollout, it involves changing three fields: 1. Replacing the `apiVersion` from `apps/v1` to `argoproj.io/v1alpha1` 1. Replacing the `kind` from `Deployment` to `Rollout` -1. Replacing the deployment strategy with a [blue-green](features/bluegreen.md) or [canary](features/canary.md) strategy +1. Replacing the deployment strategy with a [blue-green](features/bluegreen.md) or [canary](features/canary) strategy Below is an example of a Rollout resource using the canary strategy.