Skip to content
Documentation
Using
Reference
Troubleshooting

Troubleshooting

Common Issues

Resource Stuck in “Creating” State

Symptoms: Resource shows SYNCED: False and never becomes READY.

Diagnosis:

kubectl describe <resource-type> <resource-name>

Look at the Events section and status.conditions for error messages.

Common causes:

  • Invalid providerConfigRef — ensure the referenced ProviderConfig exists
  • Incorrect credentials — verify username/password or client secret
  • Network connectivity — the provider pod cannot reach the Keycloak URL
  • Invalid field values — check the resource spec against Keycloak’s requirements

Authentication Failures

Symptoms: Events show 401 Unauthorized or 403 Forbidden.

Steps:

  1. Verify the credentials secret exists and has correct data:
    kubectl get secret keycloak-credentials -n crossplane-system -o jsonpath='{.data.credentials}' | base64 -d
  2. Test connectivity from the provider pod:
    kubectl exec -it -n crossplane-system <provider-pod> -- curl -k https://keycloak.example.com
  3. Confirm the client_id has admin privileges in Keycloak

Drift Detection Loops

Symptoms: Resource keeps updating even when no changes are made.

Common causes:

  • Fields with server-side defaults that differ from your spec
  • Timestamp or ordering differences

Solution: Ensure your spec exactly matches the desired state. Use kubectl describe to compare spec.forProvider with status.atProvider.

Unexpected make generate Diffs

Symptoms: make generate produces unexpectedly large or stale diffs.

Common cause: Stale local generator cache/artifacts.

Solution:

  1. Remove .work/ and config/schema.json.
  2. Run make generate again.

Provider Pod CrashLoopBackOff

Steps:

  1. Check pod logs:
    kubectl logs -n crossplane-system -l pkg.crossplane.io/revision --tail=100
  2. Common causes:
    • Insufficient memory (increase via DeploymentRuntimeConfig)
    • Missing CRDs (reinstall the provider)

TLS Certificate Errors

Symptoms: x509: certificate signed by unknown authority

Solutions:

  • Add the CA certificate to the credentials using root_ca_certificate
  • Or mount the CA certificate into the provider pod via DeploymentRuntimeConfig

Useful Commands 

# List all Keycloak CRDs
kubectl get crd | grep keycloak.crossplane.io

# Check provider health
kubectl get providers.pkg.crossplane.io

# View provider logs
kubectl logs -n crossplane-system -l pkg.crossplane.io/revision --tail=50

# Describe a specific resource for debugging
kubectl describe realm my-realm

# List all managed resources
kubectl get managed -l crossplane.io/provider=provider-keycloak

Getting Help

ProviderConfig