Improve documentation for AD integration

vmeoc commented 1 year ago

Description

Documentation need to be updated to be able to use the AD integration.

The documentation should provide all the properties names of the integration. We need to know how to configure the ‘Projects’ tab too, otherwise it won’t be applied to any deployment.

Describe alternatives you've considered

Test and failure have not worked so far and there's no other documentation available

References

The current documentation does not provide enough information to use the AD integration:https://github.com/vmware/terraform-provider-vra/tree/main/examples/integration

Community Note

Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
If you are interested in working on this issue or have submitted a pull request, please leave a comment

frodenas commented 1 year ago

@vmeoc which properties are missing from this example? A POST request in the vRA UI triggers the following request:

{
  "integrationProperties": {
    "server": "ldap://server.company.com",
    "endpointId": "b1c92235-db27-4aae-a5e8-c3e1d521e503",
    "user": "ADMIN",
    "privateKey": "***REDACTED***",
    "defaultOU": "dc=computers,dc=example,dc=local",
    "alternativeHost": "",
    "connectionTimeout": 10,
    "endpointType": "activedirectory",
  },
  "customProperties": {
    "isExternal": "true"
  },
  "integrationType": "activedirectory",
  "associatedCloudAccountIds": [],
  "privateKey": "***REDACTED***",
  "name": "terraform-test"
}

which can be easily replicated in terraform as:

resource "vra_integration" "ad" {
  integration_properties = {
    server: "ldap://server.company.com"
    endpointId: "b1c92235-db27-4aae-a5e8-c3e1d521e503"
    user: "ADMIN"
    defaultOU: "dc=computers,dc=example,dc=local"
    alternativeHost: ""
    connectionTimeout: 10
    endpointType: "activedirectory"
  }
  custom_properties = {
    isExternal: "true"
  }
  integration_type = "activedirectory"
  associated_cloud_account_ids = []
  private_key = "***REDACTED***"
  name = "terraform-test"
}

The projects association is something that is currently NOT supported in the terraform provider.

vmeoc commented 11 months ago

Thanks Ferran for this information. What about the mgmt of vR Ops & Ansible? Is it supported in the TF provider? If so, can you share the documentation?

frodenas commented 11 months ago

vRA only exposes generic Integration APIs, which means that all the integrations supported by vRA will also be supported by the Terraform provider out-of-the-box, as no code changes are required.

The problem is that the vRA Integration APIs do NOT expose any documentation about the properties required by each integration.

My suggestion is to go to the integrations page at vRA and using for example the Chrome inspector, check the request/responses when you create/open an integration. There you will see all the properties supported/required by each integration.

For example, for an existing Ansible Tower integration endpoint, I see that the vRA returns the following:

{
    "integrationType": "ansible.tower",
    "integrationProperties": {
        "dcId": "2e4a62b2-886d-4ec6-a5d0-c37cd0f8cc34",
        "hostName": "***REDACTED***",
        "location": "Private",
        "privateKeyId": "admin",
        "leMansAgentId": "830f46cb-d985-49d3-b3a1-b194356e830d",
        "acceptSelfSignedCertificate": "true"
    },
    "customProperties": {
        "dcId": "2e4a62b2-886d-4ec6-a5d0-c37cd0f8cc34",
        "hostName": "***REDACTED***",
        "location": "Private",
        "isExternal": "true",
        "privateKeyId": "admin",
        "acceptSelfSignedCertificate": "true"
    },
    "name": "Ansible Tower",
    "id": "2628f496-90bd-410e-b1fd-3aceb8daa1cb",
    "createdAt": "2022-10-26",
    "updatedAt": "2022-10-26",
    "orgId": "2acf4023-1778-4e6a-a892-7635b8c7f4fb",
    "_links": {
        "self": {
            "href": "/iaas/api/integrations/2628f496-90bd-410e-b1fd-3aceb8daa1cb"
        }
    }
}

With this info, you can create a TF file with the above contents:

resource "vra_integration" "ansible" {
  integration_properties = {
    dcId: "2e4a62b2-886d-4ec6-a5d0-c37cd0f8cc34"
    hostName: "***REDACTED***"
    location: "Private"
    privateKeyId: "admin"
    leMansAgentId: "830f46cb-d985-49d3-b3a1-b194356e830d"
    acceptSelfSignedCertificate: "true"
  }
  custom_properties = {
    isExternal: "true"
  }
  integration_type = "ansible.tower"
  associated_cloud_account_ids = []
  private_key = "***REDACTED***"
  name = "Ansible Tower"
}

Apologies for not providing more clear examples, but I think this goes outside of the scope of the provider and needs to be documented in vRA so external components can consume it. Anyway, I hope the above example helps.

vmware / terraform-provider-vra