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

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


channel_block -- Fetch blocks for a Hyperledger Fabric channel
==============================================================

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


Synopsis
--------

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

  state
    ``absent`` - If a block exists at the specified *path*, it will be removed.

    ``present`` - Fetch the block from the specified channel and store it at the specified *path*.

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

  ordering_service (required)
    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``.

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

    Cannot be specified with *ordering_service*.

    | **Type**: raw

  identity (required)
    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.

    | **Type**: raw

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

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

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

  target (required)
    The target block to fetch.

    Can be the number of the block to fetch, or one of ``newest``, ``oldest`` or ``config``.

    | **Type**: str

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

    | **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: Fetch the genesis block for the channel
      ibm.blockchain_platform.channel_block:
        state: present
        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
        name: mychannel
        target: "0"
        path: channel_genesis_block.bin



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

  path
    The path to the file where the channel block is stored.

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


