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

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


channel_config -- Manage the configuration for a Hyperledger Fabric channel
===========================================================================

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


Synopsis
--------

Fetch and update the configuration for a Hyperledger Fabric channel by using the IBM Blockchain Platform.

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

  operation (required)
    ``create`` - Create a channel configuration update transaction for a new channel.

    ``fetch`` - Fetch the current channel configuration to the specified *path*.

    ``compute_update`` - Compute a channel configuration update transaction using the original configuration at *origin* and the updated configuration at *updated*.

    ``sign_update`` - Sign a channel configuration update transaction.

    ``apply_update`` - Apply a channel configuration update transaction.

    | **Type**: str

  ordering_service
    The ordering service to use to manage the channel.

    You can pass a string, which is the cluster name of a ordering service registered with the IBM Blockchain Platform console.

    You can also pass a list, which must match the result format of one of the :ref:`ordering_service_info <ordering_service_info_module>` or :ref:`ordering_service <ordering_service_module>` modules.

    Only required when *operation* is ``fetch`` or ``apply_update``.

    Cannot be specified with *ordering_service_nodes*.

    | **Type**: raw

  ordering_service_nodes
    The ordering service nodes to use to manage the channel.

    You can pass strings, which are the names of ordering service nodes that are registered with the IBM Blockchain Platform console.

    You can also pass a dict, which must match the result format of one of the :ref:`ordering_service_node_info <ordering_service_node_info_module>` or :ref:`ordering_service_node <ordering_service_node_module>` modules.

    Only required when *operation* is ``fetch`` or ``apply_update``.

    Cannot be specified with *ordering_service*.

    If specified when *operation* is ``create``, then the specified ordering service nodes are used as the consenters for the channel. This is useful when you want to use a subset of nodes in an ordering service; for example, when you only want to use three ordering service nodes from a five node ordering service.

    | **Type**: raw

  identity
    The identity to use when interacting with the ordering service or for signing channel configuration update transactions.

    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.

    Only required when *operation* is ``fetch``, ``sign_update``, or ``apply_update``.

    | **Type**: raw

  msp_id
    The MSP ID to use for interacting with the ordering service or for signing channel configuration update transactions.

    Only required when *operation* is ``fetch``, ``sign``, or ``apply_update``.

    | **Type**: str

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

    Only required if the identity specified in *identity* was enrolled using an HSM, and when *operation* is ``fetch``, ``sign``, or ``apply_update``.

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


  name (required)
    The name of the channel.

    | **Type**: str

  path (required)
    The path to the file where the channel configuration or the channel configuration update transaction will be stored.

    | **Type**: str

  original
    The path to the file where the original channel configuration is stored.

    Only required when *operation* is ``compute_update``.

    | **Type**: str

  updated
    The path to the file where the updated channel configuration is stored.

    Only required when *operation* is ``compute_update``.

    | **Type**: str

  organizations
    The list of organizations to add as members in the new channel.

    The organizations must all be members of the consortium.

    You can pass strings, which are the names of organizations that are registered with the IBM Blockchain Platform console.

    You can also pass a dict, which must match the result format of one of the :ref:`organization_info <organization_info_module>` or :ref:`organization <organization_module>` modules.

    Only required when *operation* is ``create``.

    | **Type**: list
    | **Elements**: raw

  policies
    The set of policies to add to the new channel. The keys are the policy names, and the values are the policies.

    You can pass strings, which are paths to JSON files containing policies in the Hyperledger Fabric format (common.Policy).

    You can also pass a dict, which must correspond to a parsed policy in the Hyperledger Fabric format (common.Policy).

    You must provide at least an Admins, Writers, and Readers policy.

    Only required when *operation* is ``create``.

    | **Type**: dict

  acls
    The set of ACLs to add to the new channel. The keys are the ACL names, and the values are the name of the policy used by the ACL.

    | **Type**: dict

  capabilities
    The capability levels for the new channel.

    | **Type**: dict

    application
      The application capability level for the new channel.

      The value must be a valid application capability level supported by Hyperledger Fabric, and all peers that will join the new channel must support this application capability level.

      Example application capability levels include ``V1_4_2`` and ``V2_0``.

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

    channel
      The channel capability level.

      The value must be a valid channel capability level supported by Hyperledger Fabric, and all peers and ordering service nodes in the new channel must support this channel capability level.

      Example channel capability levels include ``V1_4_3`` and ``V2_0``.

      | **Type**: str

    orderer
      The orderer capability level for the new channel.

      The value must be a valid orderer capability level supported by Hyperledger Fabric, and all ordering service nodes in the new channel must support this orderer capability level.

      Example orderer capability levels include ``V1_4_2`` and ``V2_0``.

      | **Type**: str


  parameters
    The parameters for the new channel.

    | **Type**: dict

    batch_size
      The batch size parameters for the channel.

      | **Type**: dict

      max_message_count
        The maximum number of messages that should be present in a block for the channel.

        | **Type**: int

      absolute_max_bytes
        The total size of all the messages in a block for the channel must not exceed this value.

        | **Type**: int

      preferred_max_bytes
        The total size of all the messages in a block for the channel should not exceed this value.

        | **Type**: int


    batch_timeout
      The maximum time to wait before cutting a new block for the channel.

      Example values include *500ms*, *5m*, or *24h*.

      | **Type**: str


  tls_handshake_time_shift
    The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the ordering service endpoint.

    Only use this option if the ordering service TLS certificates have expired.

    The value must be a duration, for example *30m*, *24h*, or *6h30m*.

    | **Type**: str








Examples
--------

.. code-block:: yaml+jinja

    
    - name: Create the configuration for a new channel
      ibm.blockchain_platform.channel_config:
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        operation: create
        name: mychannel
        path: channel_config_update.bin
        organizations:
          - Org1
        policies:
          Admins: admins-policy.json
          Readers: readers-policy.json
          Writers: writers-policy.json

    - name: Fetch the channel configuration
      ibm.blockchain_platform.channel_config:
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        ordering_service: Ordering Service
        identity: Org1 Admin.json
        msp_id: Org1MSP
        operation: fetch
        name: mychannel
        path: channel_config.bin

    - name: Compute the configuration update for the channel
      ibm.blockchain_platform.channel_config:
        operation: compute_update
        name: mychannel
        original: original_channel_config.bin
        updated: updated_channel_config.bin
        path: channel_config_update.bin

    - name: Sign the configuration update for the channel
      ibm.blockchain_platform.channel_config:
        operation: sign_update
        identity: Org1 Admin.json
        msp_id: Org1MSP
        name: mychannel
        path: channel_config_update.bin

    - name: Apply the configuration update for the channel
      ibm.blockchain_platform.channel_config:
        api_endpoint: https://ibp-console.example.org:32000
        api_authtype: basic
        api_key: xxxxxxxx
        api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        ordering_service: Ordering Service
        identity: Org1 Admin.json
        msp_id: Org1MSP
        operation: apply_update
        name: mychannel
        path: channel_config_update.bin



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

  path
    The path to the file where the channel configuration or the channel configuration update transaction is stored.

    | **Returned**: always
    | **Type**: str


