Skip to content

docs: add DependenciesNotReady troubleshooting and fix make target #450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kvaps merged 2 commits into from
Mar 12, 2026
Merged

docs: add DependenciesNotReady troubleshooting and fix make target #450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a547b89
docs: add troubleshooting guide for DependenciesNotReady packages
kvaps Mar 12, 2026
16e3052
docs: fix make target name in packages management guide
kvaps Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/en/docs/v1/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ To build the cozystack container with an updated chart:

```shell
cd packages/core/installer # Go to the cozystack package
make image-cozystack # Build cozystack image
make image-packages # Build packages image
make apply # Apply to the cluster
kubectl get pod -n cozy-system # Check if everything works as expected
kubectl get hr -A # Check HelmRelease objects
Expand Down
40 changes: 40 additions & 0 deletions content/en/docs/v1/operations/troubleshooting/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,46 @@ tenant-root tenant-root 4m1s True Rele

Normally all of them should be `Ready` and `Release reconciliation succeeded`

## Packages stuck in DependenciesNotReady

If some packages show `DependenciesNotReady` status:

```console
$ kubectl get pkg -A | grep -v True
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The grep -v True command is a bit broad as it will show any package that is not ready, regardless of the reason. To make the command more specific to the issue described in this section (DependenciesNotReady), it would be more precise to filter on the status message directly, based on the example output provided.

Suggested change
$ kubectl get pkg -A | grep -v True
$ kubectl get pkg -A | grep "dependencies are not ready"

NAME VARIANT READY STATUS
cozystack.cozystack-basics default False One or more dependencies are not ready
cozystack.tenant-application default False One or more dependencies are not ready
cozystack.monitoring-application default False One or more dependencies are not ready
```

This usually means a package in the dependency chain is missing or disabled. To diagnose:

1. **Find the root cause** — check the operator logs for `"dependency not found"` messages:

```bash
kubectl logs -n cozy-system deploy/cozystack-operator | grep "dependency not found"
```

This will show which dependency is missing, for example:

```
dependency not found, marking as not ready package=cozystack.monitoring-application dependency=cozystack.postgres-operator
```

2. **Check if you disabled a required package** — some packages have dependencies on other packages. If you disabled a package (e.g. `cozystack.postgres-operator`) that other packages depend on, the entire dependency chain will be blocked.
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This is a good point. To make it more actionable for the user, you could add a hint on how to check for disabled packages. For example, by mentioning where to look for the disabledPackages list.

Suggested change
2. **Check if you disabled a required package** — some packages have dependencies on other packages. If you disabled a package (e.g. `cozystack.postgres-operator`) that other packages depend on, the entire dependency chain will be blocked.
2. **Check if you disabled a required package** — some packages have dependencies on other packages. If you disabled a package (e.g. `cozystack.postgres-operator`) that other packages depend on, the entire dependency chain will be blocked. You can check for disabled packages in your `cozystack.cozystack-platform` Package resource, under `spec.components.platform.values.bundles.disabledPackages`.


3. **Fix the issue** — either re-enable the disabled package, or if you intentionally want to keep it disabled, add it to `ignoreDependencies` on the affected package:

```bash
kubectl edit pkg cozystack.monitoring-application
```

```yaml
spec:
ignoreDependencies:
- cozystack.postgres-operator
```

## Specific Troubleshooting Guides

### Cluster Bootstrapping
Expand Down