konfig-konector API Reference

Common Status Fields

Every resource exposes the following status fields:

• conditions — Standard Kubernetes conditions array. The key condition is type: Ready with status: "True" or "False".
• observedGeneration — The metadata.generation that was last reconciled. Used to gate update calls — if observedGeneration == generation, expensive describe + diff logic is skipped on re-queues triggered by drift detection.
• lastSyncTime — RFC3339 timestamp of the most recent successful reconciliation.
• Resource-specific fields such as arn, id, endpoint, etc. are documented per resource.

Cross-Resource References

Resources can reference other CRs by name instead of hardcoding AWS IDs. For example, a Subnet can reference a VPC CR:

• vpcRef.name: my-vpc — looks up the VPC CR in the same namespace and reads its status.vpcId.
• If the referenced CR does not exist or is not yet Ready, the controller re-queues and waits. No polling loop is needed in your manifests.
• You can also use a direct AWS ID or ARN (e.g. vpcRef.id: vpc-0abc123) to reference resources not managed by konfig-konector.

Ready Condition Reasons

The Ready condition's reason field conveys the current reconciliation state:

• Synced — Resource exists in AWS and matches spec.
• Creating — AWS API call in progress (async resources).
• Updating — Update API call in progress.
• Deleting — Deletion in progress, waiting for AWS to confirm.
• DependencyNotReady — A referenced CR (e.g. VPC, IAMRole) is not yet Ready.
• Error — AWS API returned a non-retryable error. Check message field for details.
• Throttled — AWS rate limit hit; controller will back off and retry automatically.

Deletion Behavior Patterns

All resources use a Kubernetes finalizer (aws.konfig.io/finalizer) to ensure the AWS resource is deleted before the CR is garbage-collected. There are three common patterns:

• Immediate — The AWS delete API call returns quickly. The finalizer is removed and the CR disappears within seconds.
• Async — The delete is initiated but takes time (e.g. NatGateway, EKS). The controller polls until the resource is fully deleted, then removes the finalizer. The CR stays in a Deleting state during this time.
• Blocked — AWS refuses to delete because the resource is in use or has dependents (e.g. non-empty S3 bucket, VPC with subnets). The CR stays with Ready: False, reason: Error. Delete dependents first, then re-trigger deletion.

Drift Detection

Every controller re-queues after 5 minutes. On each reconcile, it fetches the live AWS resource and compares it against spec. If AWS state has drifted (e.g. someone manually changed a tag or a security group rule), the controller re-applies the desired state. Updates are gated on observedGeneration: if the spec has not changed since last sync, only a describe call is made — no update API calls unless drift is detected.

Secrets & Passwords

Database passwords (for DBInstance and DBCluster) are read from Kubernetes Secrets at reconcile time via masterUserPasswordRef.name and masterUserPasswordRef.key. The password value is never written to status fields, events, or logs. On updates, the password is re-read and compared; if it has changed, the controller calls ModifyDBInstance to rotate it.