..
.. SPDX-License-Identifier: Apache-2.0
..

:github_url: https://github.com/IBM-Blockchain/ansible-collection/edit/main/plugins/modules/external_organization.py


external_organization -- Manage an external Hyperledger Fabric organization
===========================================================================

.. contents::
   :local:
   :depth: 1


Synopsis
--------

Import or remove an external Hyperledger Fabric organization by using the IBM Blockchain Platform.

A Hyperledger Fabric organziation is also known as a Membership Services Provider (MSP).

This module works with the IBM Blockchain Platform managed service running in IBM Cloud, or the IBM Blockchain Platform software running in a Red Hat OpenShift or Kubernetes cluster.






Parameters
----------

  api_endpoint (required)
    The URL for the IBM Blockchain Platform console.

    | **Type**: str

  api_authtype (required)
    ``ibmcloud`` - Authenticate to the IBM Blockchain Platform console using IBM Cloud authentication. You must provide a valid API key using *api_key*.

    ``basic`` - Authenticate to the IBM Blockchain Platform console using basic authentication. You must provide both a valid API key using *api_key* and API secret using *api_secret*.

    | **Type**: str

  api_key (required)
    The API key for the IBM Blockchain Platform console.

    | **Type**: str

  api_secret
    The API secret for the IBM Blockchain Platform console.

    Only required when *api_authtype* is ``basic``.

    | **Type**: str

  api_timeout
    The timeout, in seconds, to use when interacting with the IBM Blockchain Platform console.

    | **Type**: int
    | **Default value**: ``60``

  api_token_endpoint
    The IBM Cloud IAM token endpoint to use when using IBM Cloud authentication.

    Only required when *api_authtype* is ``ibmcloud``, and you are using IBM internal staging servers for testing.

    | **Type**: str
    | **Default value**: ``https://iam.cloud.ibm.com/identity/token``

  state
    ``absent`` - An organization matching the specified name will be stopped and removed.

    ``present`` - Asserts that an organization matching the specified name and configuration exists. If no organization matches the specified name, an organization will be created. If an organization matches the specified name but the configuration does not match, then the organization will be updated, if it can be. If it cannot be updated, it will be removed and re-created with the specified configuration.

    | **Type**: str
    | **Default value**: ``present``

  name
    The name of the external organization.

    Only required when *state* is ``absent``.

    | **Type**: str

  organization
    The definition of the external organization

    Only required when *state* is ``present``.

    | **Type**: dict

    name
      The name of the organization.

      | **Type**: str

    msp_id
      The MSP ID for the organization.

      | **Type**: str

    certificate_authority
      The certificate authority to use to build this organization.

      You can pass a string, which is the display name of a certificate authority registered with the IBM Blockchain Platform console.

      You can also pass a dictionary, which must match the result format of one of the :ref:`certificate_authority_info <certificate_authority_info_module>` or :ref:`certificate_authority <certificate_authority_module>` modules.

      | **Type**: raw

    root_certs
      The list of root certificates for this organization.

      Root certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str

    intermediate_certs
      The list of intermediate certificates for this organization.

      Intermediate certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str

    admins
      The list of administrator certificates for this organization.

      Administrator certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str

    revocation_list
      The list of revoked certificates for this organization.

      Revoked certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str

    tls_root_certs
      The list of TLS root certificates for this organization.

      TLS root certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str

    tls_intermediate_certs
      The list of TLS root certificates for this organization.

      TLS intermediate certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str

    fabric_node_ous
      Configuration specific to the identity classification.

      | **Type**: dict

      enable
        True if identity classification is enabled for this organization, false otherwise.

        | **Type**: boolean
        | **Default value**: ``True``

      admin_ou_identifier
        Configuration specific to the admin identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Default value**: ``admin``


      client_ou_identifier
        Configuration specific to the client identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Default value**: ``client``


      peer_ou_identifier
        Configuration specific to the peer identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Default value**: ``peer``


      orderer_ou_identifier
        Configuration specific to the orderer identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Default value**: ``orderer``



    organizational_unit_identifiers
      The list of organizational unit identifiers for this organization.

      | **Type**: list
      | **Elements**: dict

      certificate
        The root or intermediate certificate for this organizational unit identifier.

        Root or intermediate certificates must be supplied as base64 encoded PEM files.

        | **Type**: str

      organizational_unit_identifier
        The organizational unit (OU) identifier.

        | **Type**: str










Examples
--------

.. code-block:: yaml+jinja

    
    - name: Import the organization
      ibm.blockchain_platform.external_organization:
        status: present
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        organization: "{{ lookup('file', 'Org1.json') }}"

    - name: Remove the imported organization
      ibm.blockchain_platform.external_organization:
        state: absent
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name: Org1



Return Values
-------------

  organization
    The organization.

    | **Returned**: when *state* is ``present``
    | **Type**: dict

    name
      The name of the organization.

      | **Type**: str
      | **Sample**: ``Org1``

    msp_id
      The MSP ID for the organization.

      | **Type**: str
      | **Sample**: ``Org1MSP``

    root_certs
      The list of root certificates for this organization.

      Root certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

    intermediate_certs
      The list of intermediate certificates for this organization.

      Intermediate certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

    admins
      The list of administrator certificates for this organization.

      Administrator certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

    revocation_list
      The list of revoked certificates for this organization.

      Revoked certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

    tls_root_certs
      The list of TLS root certificates for this organization.

      TLS root certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

    tls_intermediate_certs
      The list of TLS root certificates for this organization.

      TLS intermediate certificates must be supplied as base64 encoded PEM files.

      | **Type**: list
      | **Elements**: str
      | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

    fabric_node_ous
      Configuration specific to the identity classification.

      | **Type**: dict

      enable
        True if identity classification is enabled for this organization, false otherwise.

        | **Type**: boolean
        | **Sample**: ``True``

      admin_ou_identifier
        Configuration specific to the admin identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str
          | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Sample**: ``admin``


      client_ou_identifier
        Configuration specific to the client identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str
          | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Sample**: ``client``


      peer_ou_identifier
        Configuration specific to the peer identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str
          | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Sample**: ``peer``


      orderer_ou_identifier
        Configuration specific to the orderer identity classification.

        | **Type**: dict

        certificate
          The root or intermediate certificate for this identity classification.

          Root or intermediate certificates must be supplied as base64 encoded PEM files.

          | **Type**: str
          | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

        organizational_unit_identifier
          The organizational unit (OU) identifier for this identity classification.

          | **Type**: str
          | **Sample**: ``orderer``



    organizational_unit_identifiers
      The list of organizational unit identifiers for this organization.

      | **Type**: list
      | **Elements**: dict

      certificate
        The root or intermediate certificate for this organizational unit identifier.

        Root or intermediate certificates must be supplied as base64 encoded PEM files.

        | **Type**: str
        | **Sample**: ``LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...``

      organizational_unit_identifier
        The organizational unit (OU) identifier.

        | **Type**: str
        | **Sample**: ``acctdept``




