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

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


organization -- Manage a Hyperledger Fabric organization
========================================================

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


Synopsis
--------

Create, update, or delete a 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 (required)
    The name of the organization.

    | **Type**: str

  msp_id
    The MSP ID for the organization.

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

    | **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

  registrar
    The identity to use when interacting with the certificate authority. If you want a CRL (Certificate Revocation List) generated from the certificate authority, you must supply an identity to use as the registrar.

    You can pass a string, which is the path to the JSON file where the enrolled identity is stored.

    You can also pass a dict, which must match the result format of one of the :ref:`enrolled_identity_info <enrolled_identity_info_module>` or :ref:`enrolled_identity <enrolled_identity_module>` modules.

    | **Type**: raw

  hsm
    The PKCS #11 compliant HSM configuration to use for digital signatures.

    Only required if the identity specified in *registrar* was enrolled using an HSM.

    | **Type**: dict

    pkcs11library
      The PKCS #11 library that should be used for digital signatures.

      | **Type**: str

    label
      The HSM label that should be used for digital signatures.

      | **Type**: str

    pin
      The HSM pin that should be used for digital signatures.

      | **Type**: str


  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: Create organization from a certificate authority
      ibm.blockchain_platform.organization:
        state: present
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name: Org1
        msp_id: Org1MSP
        certificate_authority: Org1 CA
        registrar: Org1 CA Admin.json
        admins:
          - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...

    - name: Create organization from certificates
      ibm.blockchain_platform.organization:
        state: present
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name: Org1
        msp_id: Org1MSP
        root_certs:
          - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
        intermediate_certs:
          - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
        tls_root_certs:
          - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
        tls_intermediate_certs:
          - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
        revocation_list:
          - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
        admins:
          - LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...

    - name: Delete organization
      ibm.blockchain_platform.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``




