Merge branch 'main' into ado-promotion-steps-support

akuity · Dec 18, 2024 · c98f968 · c98f968
2 parents bf03c7f + db17a2a
commit c98f968
Show file tree

Hide file tree

Showing 66 changed files with 3,215 additions and 1,974 deletions.
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -36,7 +36,7 @@ jobs:
         echo "Repository is set to: $REPO"
         echo "repo=$REPO" >> $GITHUB_OUTPUT
     - name: Setup Go
-      uses: actions/setup-go@41dfa10bad2bb2ae585af6ee5bb4d7d973ad74ed # v5.1.0
+      uses: actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a # v5.2.0
       with:
         go-version: '1.23.0'
     - name: Set version for unstable builds

diff --git a/Dockerfile b/Dockerfile
@@ -59,7 +59,7 @@ WORKDIR /kargo/bin
 ####################################################################################################
 # `tools` stage allows us to take the leverage of the parallel build.
 # For example, this stage can be cached and re-used when we have to rebuild code base.
-FROM curlimages/curl:8.11.0 AS tools
+FROM curlimages/curl:8.11.1 AS tools
 
 ARG TARGETOS
 ARG TARGETARCH

diff --git a/charts/kargo/templates/api/deployment.yaml b/charts/kargo/templates/api/deployment.yaml
@@ -87,24 +87,30 @@ spec:
               protocol: TCP
 {{- if .Values.api.probes.enabled }}
           livenessProbe:
+            {{- if .Values.api.tls.enabled }}
             exec:
               command:
                 - /usr/local/bin/grpc_health_probe
                 - -addr=:8080
-{{- if .Values.api.tls.enabled }}
                 - -tls
                 - -tls-no-verify
-{{- end }}
+            {{- else }}
+            grpc:
+              port: 8080
+            {{- end }}
             initialDelaySeconds: 10
           readinessProbe:
+            {{- if .Values.api.tls.enabled }}
             exec:
               command:
                 - /usr/local/bin/grpc_health_probe
                 - -addr=:8080
-{{- if .Values.api.tls.enabled }}
                 - -tls
                 - -tls-no-verify
-{{- end }}
+            {{- else }}
+            grpc:
+              port: 8080
+            {{- end }}
             initialDelaySeconds: 5
 {{- end }}
 {{- if or .Values.kubeconfigSecrets.kargo (and .Values.api.oidc.enabled .Values.api.oidc.dex.enabled) .Values.api.tls.enabled .Values.api.cabundle.configMapName .Values.api.cabundle.secretName }}

diff --git a/docs/docs/30-how-to-guides/20-managing-credentials.md b/docs/docs/30-how-to-guides/20-managing-credentials.md
@@ -5,7 +5,7 @@ sidebar_label: Managing Credentials
 
 # Managing Credentials
 
-To manage the progression of freight from stage to stage, Kargo will often
+To manage the progression of Freight from Stage to Stage, Kargo will often
 require read/write permissions on private GitOps repositories and read-only
 permissions on private container image and/or Helm chart repositories.
 
@@ -106,6 +106,50 @@ Refer to
 [the advanced section of the installation guide](./10-installing-kargo.md#advanced-installation)
 for more details.
 
+:::note
+Operators must manually ensure Kargo controllers receive read-only access
+to `Secret`s in the designated namespaces. For example, if `kargo-global-creds`
+is designated as a global credentials namespace, the following `RoleBinding`
+should be created within that `Namespace`:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+    name: kargo-controller-read-secrets
+    namespace: kargo-global-creds
+subjects:
+    - kind: ServiceAccount
+      name: kargo-controller
+      namespace: kargo
+roleRef:
+    kind: ClusterRole
+    name: kargo-controller-read-secrets
+    apiGroup: rbac.authorization.k8s.io
+```
+:::
+
+:::info
+By default, Kargo controllers lack cluster-wide permissions on `Secret`
+resources. Instead, the Kargo _management controller_ dynamically expands
+controller access to `Secret`s on a namespace-by-namespace basis as new
+`Project`s are created.
+
+_It is because this process does not account for "global" credential namespaces
+that these bindings must be created manually by an operator._
+:::
+
+:::warning
+Setting `controller.serviceAccount.clusterWideSecretReadingEnabled` setting to
+`true` during Kargo installation will grant Kargo controllers cluster-wide read
+permission on `Secret` resources.
+
+__This is highly discouraged, especially in sharded environments where this
+permission would have the undesirable effect of granting remote Kargo
+controllers read permissions on all `Secret`s throughout the Kargo control
+plane's cluster -- including `Secret`s having nothing to do with Kargo.__
+:::
+
 :::note
 Any matching credentials (exact match _or_ pattern match) found in a project's
 own `Namespace` take precedence over those found in any global credentials
@@ -125,12 +169,6 @@ searched in lexical order by name. Only after no exact match _and_ no pattern
 match is found in one global credentials `Namespace` does Kargo search the next.
 :::
 
-:::caution
-It is important to understand the security implications of this feature. Any
-credentials stored in a global credentials `Namespace` will be available to
-_all_ Kargo projects.
-:::
-
 ## Managing Credentials with the CLI
 
 The Kargo CLI can be used to manage credentials in a project's `Namespace.`

diff --git a/docs/docs/30-how-to-guides/30-managing-user-permissions.md b/docs/docs/30-how-to-guides/30-managing-user-permissions.md
@@ -273,6 +273,21 @@ kargo delete role developer --project kargo-demo
 role.rbac.kargo.akuity.io/developer deleted
 ```
 
+## Kargo Role Matrix
+
+The table below outlines the maximum rules required based on the `kargo-admin` ClusterRole. When specifying verbs, it's recommended to apply the principle of least privilege, ensuring access is limited to what is necessary for the specific role.
+
+| **API Groups**              | **Resources**                                  | **Verbs**                                           |
+|-----------------------------|------------------------------------------------|-----------------------------------------------------|
+| `""`                        | `events`, `namespaces`, `serviceaccounts`      | `get`, `list`, `watch`                              |
+| `rbac.authorization.k8s.io` | `rolebindings`, `roles`                        | `get`, `list`, `watch`                              |
+| `kargo.akuity.io`           | `freights`, `projects`, `stages`, `warehouses` | `*`                                                 |
+| `kargo.akuity.io`           | `stages`                                       | `promote`                                           |
+| `kargo.akuity.io`           | `promotions`                                   | `create`, `delete`, `get`, `list`, `patch`, `watch` |
+| `kargo.akuity.io`           | `freights/status`                              | `patch`                                             |
+| `argoproj.io`               | `analysisruns`                                 | `delete`, `get`, `list`, `watch`                    |
+| `argoproj.io`               | `analysistemplates`                            | `*`                                                 |
+
 ## Global Mappings
 
 In cases where certain, broad sets of permissions may be required by a large

diff --git a/docs/docs/35-references/10-promotion-steps.md b/docs/docs/35-references/10-promotion-steps.md
@@ -924,14 +924,32 @@ steps:
 ### `git-push`
 
 `git-push` pushes the committed changes in a specified working tree to a
-specified branch in the remote repository. This step typically follows a `git-commit` step and is often followed by a `git-open-pr` step.
+specified branch in the remote repository. This step typically follows a
+`git-commit` step and is often followed by a `git-open-pr` step.
+
+This step also implements its own, internal retry logic. If a push fails, with
+the cause determined to be the presence of new commits in the remote branch that
+are not present in the local branch, the step will attempt to rebase before
+retrying the push. Any merge conflict requiring manual resolution will
+immediately halt further attempts.
+
+:::info
+This step's internal retry logic is helpful in scenarios when concurrent
+Promotions to multiple Stages may all write to the same branch of the same
+repository.
+
+Because conflicts requiring manual resolution will halt further attempts, it is
+recommended to design your Promotion processes such that Promotions to multiple
+Stages that write to the same branch do not write to the same files.
+:::
 
 #### `git-push` Configuration
 
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
 | `path` | `string` | Y | Path to a Git working tree containing committed changes. |
 | `targetBranch` | `string` | N | The branch to push to in the remote repository. Mutually exclusive with `generateTargetBranch=true`. If neither of these is provided, the target branch will be the same as the branch currently checked out in the working tree. |
+| `maxAttempts` | `int32` | N | The maximum number of attempts to make when pushing to the remote repository. Default is 50. |
 | `generateTargetBranch` | `boolean` | N | Whether to push to a remote branch named like `kargo/<project>/<stage>/promotion`. If such a branch does not already exist, it will be created. A value of 'true' is mutually exclusive with `targetBranch`. If neither of these is provided, the target branch will be the currently checked out branch. This option is useful when a subsequent promotion step will open a pull request against a Stage-specific branch. In such a case, the generated target branch pushed to by the `git-push` step can later be utilized as the source branch of the pull request. |
 
 #### `git-push` Examples

diff --git a/docs/docs/45-resources.md b/docs/docs/45-resources.md
@@ -0,0 +1,50 @@
+---
+description: Learn about Kargo through our talks from conferences 
+sidebar_label: Resources
+---
+
+# Resources
+
+Learn more about Kargo through talks and webinars presented at conferences like KubeCon, ArgoCon, GitOpsCon, etc!
+
+## Kargo GA Webinar 🎉
+By Kelsey Hightower & Jesse Suen
+
+<center>
+<div style={{position: "relative", width: "100%", "padding-top": "56.25%"}}>
+  <iframe style={{position: "absolute", top: 0, left: 0, width: "100%", height: "100%"}} src="https://www.youtube.com/embed/GvGt0yuApvE?si=UCzHwdzg7R9_mfjJ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen/>
+</div>
+</center>
+
+## Streamlining Kubernetes with Kargo
+By Christian Hernandez | GitHub OpenSourceFriday 2024
+
+<center>
+<div style={{position: "relative", width: "100%", "padding-top": "56.25%"}}>
+  <iframe style={{position: "absolute", top: 0, left: 0, width: "100%", height: "100%"}} src="https://www.youtube.com/embed/vQ8coBb-3eE?si=26tO8z9-ZoQwbv3N" title="Streamlining Kubernetes with Kargo: #OpenSourceFriday feat. Christian Hernandez" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen/>
+</div>
+</center>
+
+---
+
+## GitOps Pipelines: Everything Everywhere All at Once
+By Christian Hernandez | GitOpsCon North America 2024
+
+<center>
+<div style={{position: "relative", width: "100%", "padding-top": "56.25%"}}>
+  <iframe style={{position: "absolute", top: 0, left: 0, width: "100%", height: "100%"}} src="https://www.youtube.com/embed/ZHGWXISTP68?si=jFdESQ5yXbQn0M3D" title="GitOps Pipelines: Everything Everywhere All at Once - Christian Hernandez" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen/>
+</div>
+</center>
+
+---
+
+## Multi-Stage Deployment Pipelines the GitOps Way
+By Jesse Suen & Kent Rancourt | GitOpsCon Europe 2023
+
+<center>
+<div style={{position: "relative", width: "100%", "padding-top": "56.25%"}}>
+  <iframe style={{position: "absolute", top: 0, left: 0, width: "100%", height: "100%"}} src="https://www.youtube.com/embed/tl8w72tehZ0?si=q-uuzl64JXKyuqH1" title="Multi-Stage Deployment Pipelines the GitOps Way - Jesse Suen & Kent Rancourt" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen/>
+</div>
+</center>
+
+---
diff --git a/docs/plugins/gtag/pnpm-lock.yaml b/docs/plugins/gtag/pnpm-lock.yaml
diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml