Example Playbooks (#462)

* Added 2 example playbooks for Issue #414

Signed-off-by: rthatcher <robert.thatcher@uk.ibm.com>

* Update Channel Parameters example added for Issue #414

Signed-off-by: rthatcher <robert.thatcher@uk.ibm.com>

* Changes made after review

Signed-off-by: rthatcher <robert.thatcher@uk.ibm.com>

* Fix linting error

Signed-off-by: Simon Stone <sstone1@uk.ibm.com>

Co-authored-by: Simon Stone <sstone1@uk.ibm.com>

docs/source/tasks/enable-fabricv2-capability.rst

@@ -0,0 +1,113 @@
+..
+.. SPDX-License-Identifier: Apache-2.0
+..
+
+Enable Hyperledger Fabric v2 Capability
+=======================================
+
+Fabric v2 capability is distinct from Fabric v2.x binaries, and the most common scenario will be where the binaries on a network have been upgraded to v2.x, leaving the Capability of the channels at V1.x.  This playbook example can be used to upgrade firstly the system channel, then an array of named application channels.
+
+Note that when an application channel has been upgraded to v2 capability it is incompatible with the Fabric v1.x chaincode lifecycle, and the new v2.* lifecycle must be used to upgrade or deploy new chaincodes (contracts).
+
+v2 capability should only be enabled when all nodes on the network are running v2.x binaries.
+
+Before you start
+----------------
+
+This task guide assumes that you have installed Ansible and the IBM Blockchain Platform collection for Ansible, and are familiar with how to use these technologies.
+
+Cloning the repository
+----------------------
+
+This task guide uses a set of example playbooks which are stored in a GitHub repository. You must clone this GitHub repository in order to run the playbooks locally:
+
+    .. highlight:: none
+
+    ::
+
+        git clone https://github.com/IBM-Blockchain/ansible-collection.git
+
+After cloning the GitHub repository, you must change into the examples directory for this task guide:
+
+    ::
+
+        cd ansible-collection/examples/enable-fabricv2-capability
+
+Editing the variable file
+-------------------------
+
+You need to edit the variable file ``vars.yml``. This file is used to pass information about your network into the example Ansible playbooks.
+
+The first set of values that you must set depend on whether the organization is using the IBM Blockchain Platform on IBM Cloud, or the IBM Blockchain Platform software:
+
+* If the organization is using IBM Blockchain Platform on IBM Cloud:
+
+  1. Create service credentials for the IBM Blockchain Platform service instance, if they have not been created already.
+  2. Set ``api_endpoint`` to the value of ``api_endpoint`` specified in the service credentials.
+  3. Set ``api_authtype`` to ``ibmcloud``.
+  4. Set ``api_key`` to the value of ``api_key`` specified in the service credentials.
+  5. Note that you do not need to specify a value for ``api_secret``.
+
+* If the organization is using IBM Blockchain Platform software:
+
+  1. Determine the URL of your IBM Blockchain Platform console.
+  2. Determine the API key and secret you use to access your IBM Blockchain Platform console. You can also use a username and password instead of an API key and secret.
+  3. Set ``api_endpoint`` to the URL of your IBM Blockchain Platform console.
+  4. Set ``api_authtype`` to ``basic``.
+  5. Set ``api_key`` to your API key or username.
+  6. Set ``api_secret`` to your API secret or password.
+
+The second set of values must always be set:
+
+* Set ``ordering_service_name`` to the name of the ordering service, for example ``Ordering Service``.
+* Set ``organization_name`` to the name of the organization.
+* Set ``organization_msp_id`` to the MSP ID of the organization.
+* Set ``organization_admin_identity`` to the path of a JSON identity file containing the identity of the organization administrator.
+* Set ``ordering_service_admin_identity`` to the path to a JSON identity file containing the identity of an ordering service administrator.
+* Set ``ordering_service_admin_msp_id`` to the MSP ID of the ordering service administrator.
+* Set ``channel_names`` to an array of channel names that need to have Fabric v2 capability enabled. Do not include the system channel name in this value.
+
+
+
+Enabling v2 Capability for the System Channel
+---------------------------------------------
+
+The first task is to enable v2 capability on the system channel of the Orderer.
+Note that any new channels created after updating the System Channel will have v2 capability enabled by default, but readers are encouraged to verify that all the capabilities are enabled for the new channels.
+
+Review the example playbook `01-enable-fabricv2-systemchannel.yml <https://github.com/IBM-Blockchain/ansible-collection/blob/master/examples/enable-fabricv2-capability/01-enable-fabricv2-systemchannel.yml>`_.
+
+Ensure that the JSON identity files specified in the ``vars.yml`` file have been copied to the working directory.
+
+Run the playbook as follows:
+
+  ::
+
+    ansible-playbook 01-enable-fabricv2-systemchannel.yml
+
+Ensure that the example playbook completed successfully by examining the ``PLAY RECAP`` section in the output from Ansible.
+
+
+Enabling v2 Capability for Specified Channels
+---------------------------------------------
+
+The second step in this task is to enable v2 capability for the application channels.  Application channels do not have to be v2 enabled immediately after the system channel, channels can continue to run with V1.x capability if required.
+
+Note that when you have enabled v2 Capability on a channel you are commited to using the new v2 Chaincode Lifecycle on that channel.
+
+v2 capability requires that a *Channel Application Endorsement Policy* be added to the channel.  This playbook uses an example policy ``endorsement-policy.json``.
+v2 capability enables a default majority Lifecycle Endorsement Policy, but if a different policy is required, this playbook can be modified to include such a policy at the time v2 capability is enabled.
+
+In this example playbook both the Ordering Service Administrator identity, and the Organisation Administrator identity are used to sign the modified channel configuration but in other scenarios these identities for signing may be different.
+
+Review the example playbook `02-enable-fabricv2-channels.yml <https://github.com/IBM-Blockchain/ansible-collection/blob/master/examples/enable-fabricv2-capability/02-enable-fabricv2-channels.yml>`_.
+
+When reviewing the playbook you will note that an additional playbook is used on a loop across the array of channels listed in the variables file  `02-enable-fabricv2-channel.yml <https://github.com/IBM-Blockchain/ansible-collection/blob/master/examples/enable-fabricv2-capability/tasks/02-enable-fabricv2-channel.yml>`_.
+
+Run the playbook as follows:
+
+  ::
+
+    ansible-playbook 02-enable-fabricv2-channels.yml
+
+Ensure that the example playbook completed successfully by examining the ``PLAY RECAP`` section in the output from Ansible.

docs/source/tasks/haca.rst

@@ -0,0 +1,82 @@
+..
+.. SPDX-License-Identifier: Apache-2.0
+..
+
+Creating a highly available Certificate Authority
+=================================================
+
+The default certificate authority in IBM Blockchain Platform is a single replica with an integrated SQLite database, however it is possible to configure the certificate authority to have an external PostgresSQL database and have multiple replicas of the certificate authority.
+
+The IBM Blockchain Platform documentation describes some limitations with the creation of replicas, including the restriction that an existing certificate authority with an integrated SQLite database cannot be upgraded to use a PostgresSQL database.  Consequently, the playbook for this task checks for the existence of the named certificate authority and fails if it already exists.
+
+Before you start
+----------------
+
+This task guide assumes that you have installed Ansible and the IBM Blockchain Platform collection for Ansible, and are familiar with how to use these technologies.
+
+This task guide also assumes that you have created a PostgresSQL database and that you have the connection details available.
+
+Cloning the repository
+----------------------
+
+This task guide uses a set of example playbooks which are stored in a GitHub repository. You must clone this GitHub repository in order to run the playbooks locally:
+
+    .. highlight:: none
+
+    ::
+
+        git clone https://github.com/IBM-Blockchain/ansible-collection.git
+
+After cloning the GitHub repository, you must change into the examples directory for this task guide:
+
+    ::
+
+        cd ansible-collection/examples/create-ha-ca
+
+Editing the variable file
+-------------------------
+
+You need to edit the variable file ``vars.yml``. This file is used to pass information about your network into the example Ansible playbook.
+
+The first set of values that you must set depend on whether the organization is using the IBM Blockchain Platform on IBM Cloud, or the IBM Blockchain Platform software:
+
+* If the organization is using IBM Blockchain Platform on IBM Cloud:
+
+  1. Create service credentials for the IBM Blockchain Platform service instance, if they have not been created already.
+  2. Set ``api_endpoint`` to the value of ``api_endpoint`` specified in the service credentials.
+  3. Set ``api_authtype`` to ``ibmcloud``.
+  4. Set ``api_key`` to the value of ``api_key`` specified in the service credentials.
+  5. Note that you do not need to specify a value for ``api_secret``.
+
+* If the organization is using IBM Blockchain Platform software:
+
+  1. Determine the URL of your IBM Blockchain Platform console.
+  2. Determine the API key and secret you use to access your IBM Blockchain Platform console. You can also use a username and password instead of an API key and secret.
+  3. Set ``api_endpoint`` to the URL of your IBM Blockchain Platform console.
+  4. Set ``api_authtype`` to ``basic``.
+  5. Set ``api_key`` to your API key or username.
+  6. Set ``api_secret`` to your API secret or password.
+
+The remaining values must always be set:
+
+* Set ``ha_ca_name`` to the name of the new certificate authority, for example ``HAOrg1 CA``.
+* Set ``ca_admin_identity`` to the name of the CA administrator enroll ID.
+* Set ``ca_admin_pass`` to the CA administrator enroll secret.
+* Set ``ca_admin_type`` to ``client`` if you are **not** using NodeOU support or ``admin`` if you **are** using NodeOU support.
+* Set ``db_datasource`` to the connection details for your PostgresSQL database, for example:
+ ``host=mypostgressql.example.com port=999 user=myUsername password=myPassword dbname=mydb sslmode=verify-full``
+* Set ``db_certfile1`` to the Base64 encoded value of the certificate for the PostgresSQL database.
+* Set ``ca_replicas`` to the number of replicas of the ca that you require.
+
+
+Creating the certificate authority
+----------------------------------
+
+Review the example playbook `create-ha-ca.yml <https://github.com/IBM-Blockchain/ansible-collection/blob/master/examples/haca/create-ha-ca.yml>`_, then run it as follows:
+
+  ::
+
+    ansible-playbook create-ha-ca.yml
+
+Ensure that the example playbook completed successfully by examining the ``PLAY RECAP`` section in the output from Ansible.
+

docs/source/tasks/update-channel-parameters.rst

@@ -0,0 +1,85 @@
+..
+.. SPDX-License-Identifier: Apache-2.0
+..
+
+Updating Channel Parameters
+===========================
+
+Hyperledger Fabric allows each channel to be configured with specific BatchSize parameters and a BatchTimeout for blocks.  This playbook example shows how an Architect or Chaincode Developer could to set these values for a particular application channel on IBM Blockchain Platform.
+
+The details and implications of setting the parameters is covered in the Hyperledger Fabric documentation set.
+
+Before you start
+----------------
+
+This task guide assumes that you have installed Ansible and the IBM Blockchain Platform collection for Ansible, and are familiar with how to use these technologies.
+
+This task guide also assumes that you have created a PostgresSQL database and that you have the connection details available.
+
+Cloning the repository
+----------------------
+
+This task guide uses a set of example playbooks which are stored in a GitHub repository. You must clone this GitHub repository in order to run the playbooks locally:
+
+    .. highlight:: none
+
+    ::
+
+        git clone https://github.com/IBM-Blockchain/ansible-collection.git
+
+After cloning the GitHub repository, you must change into the examples directory for this task guide:
+
+    ::
+
+        cd ansible-collection/examples/create-ha-ca
+
+Editing the variable file
+-------------------------
+
+You need to edit the variable file ``vars.yml``. This file is used to pass information about your network into the example Ansible playbook.
+
+The first set of values that you must set depend on whether the organization is using the IBM Blockchain Platform on IBM Cloud, or the IBM Blockchain Platform software:
+
+* If the organization is using IBM Blockchain Platform on IBM Cloud:
+
+  1. Create service credentials for the IBM Blockchain Platform service instance, if they have not been created already.
+  2. Set ``api_endpoint`` to the value of ``api_endpoint`` specified in the service credentials.
+  3. Set ``api_authtype`` to ``ibmcloud``.
+  4. Set ``api_key`` to the value of ``api_key`` specified in the service credentials.
+  5. Note that you do not need to specify a value for ``api_secret``.
+
+* If the organization is using IBM Blockchain Platform software:
+
+  1. Determine the URL of your IBM Blockchain Platform console.
+  2. Determine the API key and secret you use to access your IBM Blockchain Platform console. You can also use a username and password instead of an API key and secret.
+  3. Set ``api_endpoint`` to the URL of your IBM Blockchain Platform console.
+  4. Set ``api_authtype`` to ``basic``.
+  5. Set ``api_key`` to your API key or username.
+  6. Set ``api_secret`` to your API secret or password.
+
+The remaining values must always be set:
+
+* Set ``ordering_service_name`` to the name of the ordering service, for example ``Ordering Service``.
+* Set ``organization_name`` to the name of the organization.
+* Set ``organization_msp_id`` to the MSP ID of the organization.
+* Set ``organization_admin_identity`` to the path of a JSON identity file containing the identity of the organization administrator.
+* Set ``ordering_service_admin_identity`` to the path to a JSON identity file containing the identity of an ordering service administrator.
+* Set ``ordering_service_admin_msp_id`` to the MSP ID of the ordering service administrator.
+* Set ``target_channel`` to the name of the  channel that you want to update parameters.
+* Set ``ch_max_message_count`` to the maximum number of transactions in a Block for the target channel.
+* Set ``ch_absolute_max_bytes`` to the absolute maximum Block size for the target channel.
+* Set ``ch_preferred_max_bytes`` to the preferred maximum Block size for the target channel.
+* Set ``ch_batch_timeout`` to the amount of time to wait after the first transaction before cutting a Block for the target channel.
+
+
+Updating the channel parameters
+-------------------------------
+
+Review the example playbook `update-channel-parameters.yml <https://github.com/IBM-Blockchain/ansible-collection/blob/master/examples/update-channel-parameters/update-channel-parameters.yml>`_, then run it as follows:
+
+  ::
+
+    ansible-playbook update-channel-parameters.yml
+
+Ensure that the example playbook completed successfully by examining the ``PLAY RECAP`` section in the output from Ansible.
+

examples/create-ha-ca/create-ha-ca.yml

@@ -0,0 +1,56 @@
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+---
+- name: Create HA CA
+  hosts: localhost
+  vars_files:
+    - vars.yml
+  tasks:
+    - name: Get the certificate authority details
+      ibm.blockchain_platform.certificate_authority_info:
+        api_endpoint: "{{ api_endpoint }}"
+        api_authtype: "{{ api_authtype }}"
+        api_key: "{{ api_key }}"
+        api_secret: "{{ api_secret | default(omit) }}"
+        name: "{{ ha_ca_name }}"
+      register: certificate_authority_info
+
+    - name: Fail if the CA already exists
+      fail:
+        msg: Certificate Authority {{ ha_ca_name }} already exists
+      when: certificate_authority_info.exists
+
+    - name: Create certificate authority
+      ibm.blockchain_platform.certificate_authority:
+        state: present
+        api_endpoint: "{{ api_endpoint }}"
+        api_authtype: "{{ api_authtype }}"
+        api_key: "{{ api_key }}"
+        api_secret: "{{ api_secret | default(omit) }}"
+        name: "{{ ha_ca_name }}"
+        config_override:
+          ca:
+            registry:
+              maxenrollments: -1
+              identities:
+                - name: "{{ ca_admin_identity }}"
+                  pass: "{{ ca_admin_pass }}"
+                  type: client
+                  maxenrollments: -1
+                  attrs:
+                    hf.Registrar.Roles: "*"
+                    hf.Registrar.DelegateRoles: "*"
+                    hf.Revoker: true
+                    hf.IntermediateCA: true
+                    hf.GenCRL: true
+                    hf.Registrar.Attributes: "*"
+                    hf.AffiliationMgr: true
+            db:
+              type: postgres
+              datasource: "{{ db_datasource }}"
+              tls:
+                enabled: true
+                certfiles:
+                  - "{{ db_certfile1 }}"
+        replicas: "{{ ca_replicas }}"

examples/create-ha-ca/vars.yml

@@ -0,0 +1,14 @@
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+---
+api_endpoint: https://ibp-console.example.org:32000
+api_authtype: basic
+api_key: xxxxxxxx
+api_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ha_ca_name: HAOrg1 CA
+ca_admin_identity: haadmin
+ca_admin_pass: haadminpw
+db_datasource: host=mypostgressql.example.com port=999 user=myUsername password=myPassword dbname=mydb sslmode=verify-full
+db_certfile1: LS0tLS...
+ca_replicas: 2