rancher
/
fleet-docs
mirror of https://github.com/rancher/fleet-docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document GitRepo, HelmOps and Cluster status fields and conditions 

Refers to #3590
This commit is contained in:
Patrick Seidensal 2025-06-25 11:13:43 +02:00
parent f7c02e775e
commit fc2ac1254c
No known key found for this signature in database
1 changed files with 329 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

366
docs/ref-status-fields.md
View File

@ -1,77 +1,285 @@
# Status Fields
## Cluster and Bundle Display States
<!-- markdownlint-disable MD024 -->
Clusters and Bundles have different states in each phase of applying Bundles.
## Display States
GitRepos, HelmOps, Clusters and Bundles have different states in each phase of
applying Bundles.
Since the states from the BundleDeployments are propagated to the Bundle,
GitRepo, Cluster and ClusterGroup, you will find them to be displayed there in
the same way. The difference is the perspective on the resources.
By looking at the GitRepo, the states of all resources related to the GitRepo
are displayed there. When looking at the Cluster, the states of all Bundles in
that Cluster are displayed, which may span over many GitRepos. When looking at
the Bundle, the states of all BundleDeployments in that Bundle are displayed.
### Ready Condition
The `Ready` condition is used to determine if the BundleDeployments are in a
`Ready` state. The `Ready` condition is set to `True` if all BundleDeployments
are in the `Ready` state. If at least one BundleDeployment is not in the `Ready`
state, the `Ready` condition is set to `False`.
All the states of the BundleDeployments are aggregated into the `message` field
of the `Ready` status condition, but to prevent the message from becoming too
long, only the first 10 states are shown. The `message` field contains the
number of BundleDeployments in each state, followed by the Cluster name where
the BundleDeployment is located. `Ready` statuses are excluded from the
`message` field. For example:
```yaml
status:
conditions:
- lastUpdateTime: "2025-06-25T14:59:35Z"
message: WaitApplied(1) [Cluster fleet-default/downstream4]
status: "False"
type: Ready
```
#### Ready Status Determination
Fleet uses the `kstatus` package of `sigs.k8s.io/cli-utils` module to determine
the Ready status of BundleDeployments based on the status of its resources. For
an in-depth explanation of how the Ready status is determined, see the
[README](https://pkg.go.dev/sigs.k8s.io/cli-utils@v0.37.2/pkg/kstatus#section-readme)
of the `kstatus` package.
#### Propagation of Ready Status
```mermaid
flowchart TB
subgraph Upstream Cluster
gr[GitRepo]
c[Cluster]
cg[ClusterGroup]
b[Bundle]
bd[BundleDeployment]
end
subgraph Downstream Clusters
a[Agent]
end
gr -->|triggers creation or update| b
b -->|triggers creation or update| bd
bd -->|triggers deployment| a
a -->|updates status| bd
bd -->|triggers status update| b
bd -->|triggers status update| c
b -->|triggers status update| gr
c -->|triggers status update| cg
linkStyle 0,1,2 stroke:#0000AA,stroke-width:2px;
linkStyle 3,4,5,6,7 stroke:#00AA00,stroke-width:2px;
```
### Display State
The `status.display` field provides a more digestible summary of the state.
States are ranked and the worst possible state is used as the `state` in the
`status.display` field.
#### State Ranking
This is the ranking in which states are displayed. If a Bundle has
BundleDeployments in different states, the worst state is used in the
`status.display.state` field. This is also the state that is propagated from the
Bundles to other Fleet resources (GitRepos, Clusters, ClusterGroups).
The states are ranked from the best to the worst:
- Ready
- NotReady
- Pending
- OutOfSync
- Modified
- WaitApplied
- ErrApplied
### Bundles
**Ready**: Bundles have been deployed and all resources are ready.
#### Bundle Statuses
**NotReady**: Bundles have been deployed and some resources are not ready.
- **Ready**
**WaitApplied**: Bundles have been synced from Fleet controller and downstream cluster, but are waiting to be deployed.
If `True`, bundles have been deployed and all resources are ready. If not, the
`message` field of the `Ready` condition contains an aggregation of the states
of the BundleDeployments.
**ErrApplied**: Bundles have been synced from the Fleet controller and the downstream cluster, but there were some errors when deploying the Bundle.
- **NotReady**
**OutOfSync**: Bundles have been synced from Fleet controller, but downstream agent hasn't synced the change yet.
BundleDeployments have been deployed and some resources are not ready.
**Pending**: Bundles are being processed by Fleet controller.
For instance if the container images are being pulled, or the service has
started but not reported to be ready yet.
**Modified**: Bundles have been deployed and all resources are ready, but there are some changes that were not made from the Git Repository.
- **Pending**
Bundles are to be processed by the Fleet controller.
They might be waiting for the rollout to be resumed if it was paused (see
[Rollout Strategy](./rollout)). `Pending` is shown if there was no previously
applied BundleDeployment.
- **OutOfSync**
Bundles have been synced from the Fleet controller, but corresponding updated
BundleDeployments have not been created yet, so that the downstream agent
could not sync the change yet.
BundleDeployment creation might be waiting for the rollout to be resumed if it
was paused (see [Rollout Strategy](./rollout)). `OutOfSync` is shown if a
BundleDeployment was previously applied, but the Bundle has been modified due
to a change in the Git Repository.
- **Modified**
Bundles have been deployed and all resources are ready, but there are some
changes in the deployed resources that were not made from the Git Repository.
This happens when the deployed resources were modified externally.
- **WaitApplied**
Bundles have been synced from Fleet controller and downstream cluster, but are
waiting to be deployed.
If this state is persistently shown, the targeted Cluster may be unreachable.
- **ErrApplied**
Bundles have been synced from the Fleet controller and the downstream cluster,
but there were some errors when deploying the Bundle.
### Clusters
**WaitCheckIn**: Waiting for agent to report registration information and cluster status back.
#### Cluster specific states
**NotReady**: There are bundles in this cluster that are in NotReady state.
- **WaitCheckIn**
**WaitApplied**: There are bundles in this cluster that are in WaitApplied state.
Waiting for agent to report registration information and cluster status back.
**ErrApplied**: There are bundles in this cluster that are in ErrApplied state.
#### States from Bundles
**OutOfSync**: There are bundles in this cluster that are in OutOfSync state.
- **Ready**
**Pending**: There are bundles in this cluster that are in Pending state.
All bundles in this cluster have been deployed and all resources are ready.
**Modified**: There are bundles in this cluster that are in Modified state.
- **NotReady**
**Ready**: Bundles in this cluster have been deployed and all resources are ready.
There are bundles in this cluster that are in NotReady state.
## GitRepo Conditions
- **Pending**
**Ready**:
There are bundles in this cluster that are in Pending state.
**Active**:
- **OutOfSync**
**Reconciling**:
There are bundles in this cluster that are in OutOfSync state.
**Stalled**: for errors
- **Modified**
## HelmOp Conditions
There are bundles in this cluster that are in Modified state.
**Ready**: All bundle deployments are ready
- **WaitApplied**
**Accepted**: The HelmOp is able to properly manage deployments to target clusters. May be false if:
* Helm options are invalid
* a chart version cannot be resolved from those options
* an issue occurred when scheduling a polling job
There are bundles in this cluster that are in WaitApplied state.
**Polled**: `True` if polling is enabled and the last polling attempt was successful, `False` otherwise.
If polling is enabled, a `False` condition will contain an error message explaining the reason for the polling failure.
- **ErrApplied**
There are bundles in this cluster that are in ErrApplied state.
### GitRepo
- **Ready**
`True` if the desired state is the current state. If this is `False`, the
message field of this Condition either contains:
- an error message from the GitJob controller, or
- an error from the Bundle (e.g. when templating failed), or
- an aggregated state of the bundles that are not in a `Ready` state.
- **GitPolling**
When the remote git repository is being polled for changes or initial cloning.
Contains an error if it fails otherwise this should be `True`. This value is
also `True` if polling is disabled, since the initial cloning is preceded by
polling for the latest commit revision.
- **Reconciling**
The controller is currently working on reconciling the latest changes.
- **Stalled**
The controller has encountered an error during the reconcile process or it has
made insufficient progress (timeout).
- **Accepted**
All GitRepo restrictions could be applied and external helm secrets exist.
### HelmOp Conditions
- **Ready**
`True` if all BundleDeployments successfully have been deployed. `False` if at
least one BundleDeployments are not ready. If this is `False`, the message
field of this Condition contains an aggregated state of the bundles that are
not in a `Ready` state.
- **Accepted**
`False` if the
- Helm options are invalid
- a chart version cannot be resolved from those options
- an issue occurred when scheduling a polling job
- creation of the Bundle failed
- **Polled**
`True` if polling is enabled and the last polling attempt was
successful, `False` otherwise. If polling is enabled, a `False` condition will
contain an error message explaining the reason for the polling failure.
### `status.display`
The `status.display` fields are shared between GitRepos and GitOps. Both
resources have a `status.display` field that contains a summary of the state of
the resource. The only difference is that `state` may have a different value,
since not all values for `state` are shared by both resources.
- `readyBundleDeployments` is a string in the form "%d/%d", that describes the
number of ready bundle deployments over the total number of bundle
deployments.
- `state` represents the state of the GitRepo, such as "GitUpdating" or the
highest BundleState according to [State Rank](#state-ranking). If the state
would be `Ready`, it is set to an empty value.
- `message` contains the relevant message from the deployment conditions.
- `error` is true if an error message is present.
## Resources List
The resources lists contain the resources deployed to target clusters, categorized under `GitRepos` and `HelmOps`.
The resources lists contain the resources deployed to target clusters,
categorized under `GitRepos` and `HelmOps`.
### GitRepos
The deployed resources are listed in `GitRepos` in `status.Resources`. This list is derived from `bundleDeployments`.
The deployed resources are listed in `GitRepos` in `status.Resources`. This list
is derived from `bundleDeployments`.
### HelmOps
Similarly to what happens for `GitRepos`, the deployed resources are listed in `HelmOps` in `status.Resources`.
This list is derived from `bundleDeployments`.
Similarly to what happens for `GitRepos`, the deployed resources are listed in
`HelmOps` in `status.Resources`. This list is derived from `bundleDeployments`.
## Resource Counts
@ -80,11 +288,13 @@ This shows how resource counts are propagated from one resource to another:
### GitRepos
The `status.ResourceCounts` list for GitRepos is derived from `bundleDeployments`.
The `status.ResourceCounts` list for GitRepos is derived from
`bundleDeployments`.
### HelmOps
The `status.ResourceCounts` list for HelmOps is derived from `bundleDeployments`.
The `status.ResourceCounts` list for HelmOps is derived from
`bundleDeployments`.
### Clusters
@ -92,4 +302,86 @@ In Clusters, the `status.ResourceCounts` list is derived from GitRepos.
### ClusterGroups
In ClusterGroups, the `status.ResourceCounts` list is also derived from GitRepos.
In ClusterGroups, the `status.ResourceCounts` list is also derived from
GitRepos.
## Class Diagram
```mermaid
classDiagram
direction TB
class HelmOp {
HelmOpStatus Status
}
class GitRepo {
GitRepoStatus Status
}
class HelmOpStatus {
StatusBase
metav1.Time LastPollingTime
string Version
}
class GitRepoStatus {
StatusBase
int64 ObservedGeneration
int64 UpdateGeneration
string Commit
string WebhookCommit
string GitJobStatus
metav1.Time LastSyncedImageScanTime
metav1.Time LastPollingTime
}
class StatusBase {
int ReadyClusters
int DesiredReadyClusters
BundleSummary Summary
StatusDisplay Display
[]genericcondition.GenericCondition Conditions
[]Resource Resources
ResourceCounts ResourceCounts
map[string]*ResourceCounts PerClusterResourceCounts
}
class StatusDisplay {
string ReadyBundleDeployments
string State
string Message
bool Error
}
class BundleSummary {
int NotReady
int WaitApplied
int ErrApplied
int OutOfSync
int Modified
int Ready
int Pending
int DesiredReady
NonReadyResource[] NonReadyResources
}
class ResourceCounts {
int Ready
int DesiredReady
int WaitApplied
int Modified
int Orphaned
int Missing
int Unknown
int NotReady
}
HelmOp "1" --> "1" HelmOpStatus : Status
GitRepo "1" --> "1" GitRepoStatus : Status
HelmOpStatus "1" --|> "1" StatusBase : embeds StatusBase
GitRepoStatus "1" --|> "1" StatusBase : embeds StatusBase
StatusBase "1" --> "1" StatusDisplay : Display
StatusBase "1" --> "1" BundleSummary : Summary
StatusBase "1" --> "1" ResourceCounts : ResourceCounts
```