Part of Epic #427

Description

This issue tracks the implementation work needed to ensure the Directory resource fully complies with the External Name Handling ADR. The goal is to verify and implement proper external name handling across all CRUD operations according to the established guidelines.

Tasks

Please note, for all tasks the External Name Handling ADR acts as a source of truth, the details here are for just for reference. If deviating from the ADR, please note why.

1. Implement Proper External Name Handling

Acceptance Criteria:

• Observe() Method Implementation

• Create() Method Implementation

• Update() Method Implementation

• Delete() Method Implementation

• Review Migration Logic:

  • Evaluate existing migration logic (introduced in v1.4.0) against ADR requirements
  • Update or remove as needed to ensure ADR compliance
  • Update documentation for any breaking changes

2. Unit Test Coverage for External Name Handling

Acceptance Criteria:

• Observe() Tests:

  • Test empty external-name scenarios (witch backwards compatibility)
  • Test invalid GUID format in external-name
  • Test valid GUID that doesn't exist (404 response) → should return resourceExists: false
  • Test valid GUID that exists → normal observation flow
  • Test drift detection and diff reporting

• Create() Tests:

  • Test successful creation sets external-name to returned GUID
  • Test "resource already exists" error handling (external-name should not be set)
  • Test other creation errors (external-name should not be set)

• Update() Tests:

  • Test update with valid existing external-name
  • Test validation of immutable fields (if any)

• Delete() Tests:

  • Test deletion with valid external-name
  • Test 404 response handling (should not be treated as error)
  • Test async deletion scenarios with deletion states
  • Test deletion of externally removed resource

3. E2E Import Test Coverage

Acceptance Criteria:

• Import Flow Test:
  • Test importing existing ServiceBinding resources using the external-name annotation
  • Verify imported resources transition to healthy state with correct external-name
  • Test that imported resources can be observed and updated properly
  • Take the resuable import test in test/e2e/import_utils.go, already used in test/e2e/subaccount_test.go .

4. Upgrade Test Coverage for External Name Behavior

If this part is blocked by adding the upgrade tests to btp-provider, move this to a follow up issue.

Acceptance Criteria:

• External Name Format Migration Test:

• Backward Compatibility Validation:

  • Test that existing Subaccount resources continue to function after provider upgrade
  • Verify external-name migration logic (if implemented) works correctly
  • Ensure imported resources maintain proper external-name format post-upgrade

5. Documentation

Document the required identifier and how to obtain it in the comment block directly above the main resource struct in the <resource>_types.go file. This is used for auto-generating our docs.

Please see the generation guide for more information on the process and the required comment structure: https://github.com/SAP/crossplane-provider-btp/blob/main/docs/development/external-name-handling.md#documentation-generation

Implementation Notes

1. ADR Compliance: Ensure all implementation follows the patterns and requirements defined in the External Name Handling ADR.

2. GUID Validation: Implement proper validation for external-name format checking (GUID format expected).

3. Error Handling: Ensure API errors are properly wrapped and provide clear messages to users about external-name related issues.

4. Backward Compatibility: Evaluate existing migration logic and determine appropriate approach for maintaining or updating compatibility. This includes the already existing migration logic introduced in v1.4.0.

Related Resources

• External Name Handling ADR
• Crossplane Import Guide