Troubleshoot the JFrog Crossplane Providers

Find and fix problems with the JFrog Crossplane providers and the managed resources they reconcile.

Triage

Run the following commands to collect status, conditions, and logs:

kubectl get providers                                   # INSTALLED and HEALTHY must be True
kubectl -n crossplane-system get pods                   # one pod per provider, Running
kubectl get managed -A | grep -v 'True.*True'           # managed resources that are not Synced and Ready
kubectl describe <fq-kind>/<name> -n <ns>               # conditions and events
kubectl get <fq-kind>/<name> -n <ns> -o yaml            # annotations, status.atProvider, condition messages
kubectl -n crossplane-system logs deploy/<provider-deployment> --since=10m

Replace the following:

• <fq-kind>: The fully-qualified Kind name of the managed resource, for example localgenericrepositories.repository.artifactory.m.crossplane.io.
• <name>: The name of the managed resource.
• <ns>: The namespace of the managed resource.
• <provider-deployment>: The provider deployment in crossplane-system. To find it, see Logs and Metrics.

Check the conditions of a managed resource in this order:

1. Synced: Shows whether the reconcile loop ran.
2. LastAsyncOperation: Shows whether the JFrog API request succeeded. The status message displays the API response and HTTP status code.
3. Ready: Shows whether the object exists in the target environment.

Installation Issues

The following table lists installation symptoms with their causes and fixes.

Connection and Credentials Issues

The following table lists connection and credential error messages with their causes and fixes.

To check that the credentials Secret contains valid JSON, run the following command:

kubectl get secret jfrog-creds -n crossplane-system -o jsonpath='{.data.credentials}' | base64 -d | jq .

Reconcile Errors

The following table lists reconcile error messages with their causes and fixes.

Never-Ending Updates

Repeated UpdatedExternalResource events mean the provider updates the object on every reconcile. Compare spec.forProvider with status.atProvider. The causes are:

• Two owners for one field, for example User.groups and GroupMembers.
• A value the server normalizes: unsorted webhook eventTypes, projectEnvironments on a repository not assigned to the project, or a late-initialized proxy after you delete a Proxy.

To fix it, do one of the following:

• Write the canonical form.
• Move the field to initProvider.
• Keep one owner.

The reference lists Kind-specific cases. For more information, see JFrog Crossplane Kinds Reference.

Common JFrog API Errors

The following table lists common JFrog API error messages with their causes and fixes.

Known Issues in v0.0.1

The following table lists the known issues in this version with their workarounds.

Deletion Issues

The following table lists deletion symptoms with their fixes.

Remove a finalizer only after you confirm that the JFrog object is gone or should be kept. To remove the finalizers, run the following command:

kubectl patch <fq-kind>/<name> -n <ns> --type merge -p '{"metadata":{"finalizers":[]}}'

Verify State in JFrog

Call the JFrog REST API with the provider's URL and token (-H "Authorization: Bearer $TOKEN"). Compare the response with status.atProvider.

Expect the following timing:

• Simple objects converge within seconds of their dependencies.
• Each retry step adds up to 60 s.
• Drift is corrected within one --poll interval.
• Project deletion takes minutes.

To create a support bundle, collect the following information. Redact tokens before you share it.

• kubectl get providers,providerrevisions,deploymentruntimeconfigs -o yaml
• kubectl get managed -A -o yaml
• The Crossplane and provider logs
• kubectl get events -A --sort-by=.lastTimestamp

Logs and Metrics

Each provider revision runs as one Deployment in crossplane-system.

To find the provider deployment and read its logs:

1. List the deployments:

   Shell

   kubectl -n crossplane-system get deploy

2. Read the logs of a provider deployment:

   Shell

   kubectl -n crossplane-system logs deploy/<name>

   Replace <name> with the deployment name from the previous step.

For more detail in the logs, enable the --debug flag. For more information, see Provider Flags.

The providers serve metrics on port 8080 at the /metrics path.

Next Steps

• To review the installation steps, see Install the JFrog Crossplane Providers.
• To review the credential setup, see Configure Credentials for the JFrog Crossplane Providers.
• To understand conditions and the reconcile loop, see How the JFrog Crossplane Providers Work.
• To manage, adopt, or delete objects safely, see Manage JFrog Objects with Crossplane.
• To look up the fields and caveats of a Kind, see JFrog Crossplane Kinds Reference.