Skip to content

Commit 7abc47b

Browse files
authored
docs: add DependenciesNotReady troubleshooting and fix make target (#450)
## Summary - Add troubleshooting section for packages stuck in `DependenciesNotReady` status, explaining how to find missing dependencies in operator logs and fix them - Fix outdated `make image-cozystack` → `make image-packages` in the packages management development guide
2 parents b030984 + 16e3052 commit 7abc47b

2 files changed

Lines changed: 41 additions & 1 deletion

File tree

content/en/docs/v1/development.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,7 @@ To build the cozystack container with an updated chart:
247247

248248
```shell
249249
cd packages/core/installer # Go to the cozystack package
250-
make image-cozystack # Build cozystack image
250+
make image-packages # Build packages image
251251
make apply # Apply to the cluster
252252
kubectl get pod -n cozy-system # Check if everything works as expected
253253
kubectl get hr -A # Check HelmRelease objects

content/en/docs/v1/operations/troubleshooting/_index.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,46 @@ tenant-root tenant-root 4m1s True Rele
105105

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

108+
## Packages stuck in DependenciesNotReady
109+
110+
If some packages show `DependenciesNotReady` status:
111+
112+
```console
113+
$ kubectl get pkg -A | grep -v True
114+
NAME VARIANT READY STATUS
115+
cozystack.cozystack-basics default False One or more dependencies are not ready
116+
cozystack.tenant-application default False One or more dependencies are not ready
117+
cozystack.monitoring-application default False One or more dependencies are not ready
118+
```
119+
120+
This usually means a package in the dependency chain is missing or disabled. To diagnose:
121+
122+
1. **Find the root cause** — check the operator logs for `"dependency not found"` messages:
123+
124+
```bash
125+
kubectl logs -n cozy-system deploy/cozystack-operator | grep "dependency not found"
126+
```
127+
128+
This will show which dependency is missing, for example:
129+
130+
```
131+
dependency not found, marking as not ready package=cozystack.monitoring-application dependency=cozystack.postgres-operator
132+
```
133+
134+
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.
135+
136+
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:
137+
138+
```bash
139+
kubectl edit pkg cozystack.monitoring-application
140+
```
141+
142+
```yaml
143+
spec:
144+
ignoreDependencies:
145+
- cozystack.postgres-operator
146+
```
147+
108148
## Specific Troubleshooting Guides
109149
110150
### Cluster Bootstrapping

0 commit comments

Comments
 (0)