Skip to content

Commit ebb9659

Browse files
v-regandownerv-regandowner
authored
Merge pull request #256674 from msmbaldwin/managed-ccf-3
Azure Managed CCF initial doc release -- PR 3 of 7 (see first comment)
2 parents 88be535 + 56a5f14 commit ebb9659

7 files changed

+472
-0
lines changed

‎articles/managed-ccf/how-to-activate-members.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Activate members in an Azure Managed CCF resource
3+
description: Learn to activate the members in an Azure Managed CCF resource
4+
author: msftsettiy
5+
ms.author: settiy
6+
ms.date: 09/08/2023
7+
ms.service: confidential-ledger
8+
ms.topic: how-to
9+
ms.custom: devx-track-azurecli
10+
---
11+
12+
# Activate members in an Azure Managed CCF resource
13+
14+
In this guide, you will learn how to activate the member(s) in an Azure Managed CCF (Managed CCF) resource. This tutorial builds on the Managed CCF resource created in the [Quickstart: Create an Azure Managed CCF resource using the Azure portal](quickstart-portal.md) tutorial.
15+
16+
## Prerequisites
17+
18+
- Python 3+.
19+
- Install the latest version of the [CCF Python package](https://pypi.org/project/ccf/).
20+
21+
## Download the service identity
22+
23+
[!INCLUDE [Download Service Identity](./includes/service-identity.md)]
24+
25+
## Activate Member(s)
26+
27+
When a member is added to a Managed CCF resource, they are in the accepted state. They cannot participate in governance until they are activated. To do so, the member must acknowledge that they are satisfied with the state of the service (for example, after auditing the current constitution and the nodes currently trusted).
28+
29+
1. The member must update and retrieve the latest state digest. In doing so, the new member confirms that they are satisfied with the current state of the service.
30+
31+
```Bash
32+
curl https://confidentialbillingapp.confidential-ledger.azure.com/gov/ack/update_state_digest -X POST --cacert service_cert.pem --key member0_privk.pem --cert member0_cert.pem --silent | jq > request.json
33+
cat request.json
34+
{
35+
"state_digest": <...>
36+
}
37+
```
38+
39+
[!INCLUDE [Mac instructions](./includes/macos-instructions.md)]
40+
41+
2. The member must sign the state digest using the ccf_cose_sign1 utility. This utility is installed along with the CCF Python package.
42+
43+
```Bash
44+
ccf_cose_sign1 --ccf-gov-msg-type ack --ccf-gov-msg-created_at `date -Is` --signing-key member0_privk.pem --signing-cert member0_cert.pem --content request.json | \
45+
curl https://confidentialbillingapp.confidential-ledger.azure.com/gov/ack --cacert service_cert.pem --data-binary @- -H "content-type: application/cose"
46+
```
47+
48+
3. After the command completes, the member is active and can participate in governance. The members can be viewed using the following command.
49+
50+
[!INCLUDE [View members](./includes/view-members.md)]
51+
52+
## Next steps
53+
54+
- [Azure Managed CCF overview](overview.md)
55+
- [Quickstart: Create an Azure Managed CCF resource](quickstart-portal.md)
56+
- [Quickstart: Deploy an Azure Managed CCF application](quickstart-deploy-application.md)

‎articles/managed-ccf/how-to-backup-restore-resource.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Backup and restore an Azure Managed CCF resource
3+
description: Learn to back up and restore an Azure Managed CCF resource
4+
services: managed-ccf
5+
author: pallabpaul
6+
ms.service: confidential-ledger
7+
ms.topic: how-to
8+
ms.date: 09/07/2023
9+
ms.author: pallabpaul
10+
#Customer intent: As a developer, I want to know how to perform a backup and restore of my Managed CCF app so that I can can access backups of my app files and restore my app in another region in the case of a disaster recovery.
11+
---
12+
13+
# Perform a backup and restore
14+
15+
In this article, you'll learn to perform backup of an Azure Managed CCF (Managed CCF) resource and restore it to create a copy of the original Managed CCF resource. Here are some of the use cases that warrant this capability:
16+
17+
- A Managed CCF resource is an append only ledger at the core. It is impossible to delete few erroneous transactions without impacting the integrity of the ledger. To keep the data clean, a business could decide to recreate the resource sans the erroneous transactions.
18+
- A developer could add reference data into a Managed CCF resource and create a back of it. The developer can use the copy later to create a fresh Managed CCF resource and save time.
19+
20+
This article uses the commands found at the [Managed CCF's REST API Docs](/rest/api/confidentialledger/managed-ccf).
21+
22+
## Prerequisites
23+
24+
- Install the [Azure CLI](/cli/azure/install-azure-cli).
25+
- An Azure Storage Account.
26+
27+
## Setup
28+
29+
### Generate an access token
30+
31+
An access token is required to use the Managed CCF REST API. Execute the following command to generate an access token.
32+
33+
> [!NOTE]
34+
> An access token has a finite lifetime after which it is unusable. Generate a new token if the API request fails due to a HTTP 401 Unauthorized error.
35+
36+
```bash
37+
az account get-access-token –subscription <subscription_id>
38+
```
39+
40+
### Generate a Shared Access Signature token
41+
42+
The backup is stored in an Azure Storage Fileshare that is owned and controlled by you. The backup and restore API requests require a [Shared Access Signature](../storage/common/storage-sas-overview.md) token to grant temporary read and write access to the Fileshare. Follow these steps:
43+
44+
> [!NOTE]
45+
> A Shared Access Signature(SAS) token has a finite lifetime after which it is unusable. We recommend using short lived tokens to avoid tokens being leaked into the public and misused.
46+
47+
1. Navigate to the Azure Storage Account where the backups will be stored.
48+
2. Navigate to the `Security + networking` -> `Shared access signature` blade.
49+
3. Generate a SAS token with the following configuration:
50+
51+
:::image type="content" source="./media/how-to/cedr-sas-uri.png" lightbox="./media/how-to/cedr-sas-uri.png" alt-text="Screenshot of the Azure portal in a web browser, showing the required SAS Generation configuration.":::
52+
4. Save the `File service SAS URL`.
53+
54+
## Backup
55+
56+
### Create a backup
57+
58+
Creating a backup of the Managed CCF resource creates a Fileshare in the storage account. This backup can be used to restore the Managed CCF resource at a later time.
59+
60+
Follow these steps to perform a backup.
61+
62+
1. [Generate and save a bearer token](#generate-an-access-token) generated for the subscription that your Managed CCF resource is located in.
63+
1. [Generate a SAS token](#generate-a-shared-access-signature-token) for the Storage Account to store the backup.
64+
1. Execute the following command to trigger a backup. You must supply a few parameters:
65+
- **subscription_id**: The subscription where the Managed CCF resource is deployed.
66+
- **resource_group**: The resource group name of the Managed CCF resource.
67+
- **app_name**: The name of the Managed CCF resource.
68+
- **sas_token**: The Shared Access Signature token.
69+
- **restore_region**: An optional parameter to indicate a region where the backup would be restored. It can be ignored if you expect to restore the backup in the same region as the Managed CCF resource.
70+
```bash
71+
curl --request POST 'https://management.azure.com/subscriptions/<subscription_id>/resourceGroups/<resource_group>/providers/Microsoft.ConfidentialLedger/ManagedCCFs/<app_name>/backup?api-version=2023-06-28-preview' \
72+
--header 'Authorization: Bearer <bearer_token>' \
73+
--header 'Content-Type: application/json' \
74+
--data-raw '{
75+
"uri": "<sas_token>",
76+
"restoreRegion": "<restore_region>"
77+
}'
78+
```
79+
1. A Fileshare is created in the Azure Storage Account with the name `<mccf_app_name>-<timestamp>`.
80+
81+
### Explore the backup files
82+
83+
After the backup completes, you can view the files stored in your Azure Storage Fileshare.
84+
85+
:::image type="content" source="./media/how-to/cedr-backup-file-share.png" lightbox="./media/how-to/cedr-backup-file-share.png" alt-text="Screenshot of the Azure portal in a web browser, showing a sample Fileshare folder structure.":::
86+
87+
Refer to the following articles to explore the backup files.
88+
89+
- [Understanding your Ledger and Snapshot Files](https://microsoft.github.io/CCF/main/operations/ledger_snapshot.html)
90+
- [Viewing your Ledger and Snapshot Files](https://microsoft.github.io/CCF/main/audit/python_library.html)
91+
92+
## Restore
93+
94+
### Create a Managed CCF resource using the backup files
95+
96+
This restores the Managed CCF resource using a copy of the files in the backup Fileshare. The resource will be restored to the same state and transaction ID at the time of the backup.
97+
98+
> [!IMPORTANT]
99+
> The restore will fail if the backup files are older than 90 days.
100+
101+
> [!NOTE]
102+
> The original Managed CCF resource must be deleted before a restore is initiated. The restore command will fail if the original instance exists. [Delete your original Managed CCF resource](/cli/azure/confidentialledger/managedccfs?#az-confidentialledger-managedccfs-delete).
103+
>
104+
> The **app_name** should be the same as the original Managed CCF resource.
105+
106+
Follow these steps to perform a restore.
107+
108+
1. [Generate a Bearer token](#generate-an-access-token) for the subscription that the Managed CCF resource is located in.
109+
2. [Generate a SAS token](#generate-a-shared-access-signature-token) for the storage account that has the backup files.
110+
3. Execute the following command to trigger a restore. You must supply a few parameters.
111+
- **subscription_id**: The subscription where the Managed CCF resource is deployed.
112+
- **resource_group**: The resource group name of the Managed CCF resource.
113+
- **app_name**: The name of the Managed CCF resource.
114+
- **sas_token**: The Shared Access Signature token.
115+
- **restore_region**: An optional parameter to indicate a region where the backup would be restored. It can be ignored if you expect to restore the backup in the same region as the Managed CCF resource.
116+
- **fileshare_name**: The name of the Fileshare where the backup files are located.
117+
118+
```bash
119+
curl --request POST 'https://management.azure.com/subscriptions/<subscription_id>/resourceGroups/<resource_group>/providers/Microsoft.ConfidentialLedger/ManagedCCFs/<app_name>/restore?api-version=2023-06-28-preview' \
120+
--header 'Authorization: Bearer <bearer_token>' \
121+
--header 'Content-Type: application/json' \
122+
--data-raw '{
123+
"uri": "<sas_token>",
124+
"restoreRegion": "<restore_region>",
125+
"fileShareName": "<fileshare_name>"
126+
}'
127+
```
128+
1. At the end of the command, the Managed CCF resource is restored.
129+
130+
## Next steps
131+
132+
- [Azure Managed CCF overview](overview.md)
133+
- [Quickstart: Azure portal](quickstart-portal.md)
134+
- [Quickstart: Azure CLI](quickstart-python.md)

‎articles/managed-ccf/how-to-enable-azure-monitor.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: View application logs in Azure Monitor
3+
description: Learn to view the application logs in Azure Monitor
4+
author: msftsettiy
5+
ms.author: settiy
6+
ms.date: 09/09/2023
7+
ms.service: confidential-ledger
8+
ms.topic: how-to
9+
ms.custom: devx-track-azurecli
10+
---
11+
12+
# View the application logs in Azure Monitor
13+
14+
In this tutorial, you will learn how to view the application logs in Azure Monitor by creating a Log Analytics workspace. This tutorial builds on the Azure Managed CCF (Managed CCF) resource created in the [Quickstart: Create an Azure Managed CCF resource using the Azure portal](quickstart-portal.md) tutorial. Logs are essential pieces of information to understand, analyze and optimize the logic and performance of an application.
15+
16+
The logs from your TypeScript and JavaScript application can be viewed in Azure Monitor by creating a Log Analytics workspace.
17+
18+
## Create the Log Analytics workspace
19+
20+
1. Follow the instructions at [Create a workspace](../azure-monitor/logs/quick-create-workspace.md) to create a workspace.
21+
2. After the workspace is created, make a note of the Resource ID from the properties page.
22+
:::image type="content" source="media/how-to/log-analytics-workspace-properties.png" alt-text="Screenshot that shows the properties of a Log Analytics workspace screen.":::
23+
1. Navigate to the Managed CCF resource and make a note of the Resource ID from the properties page.
24+
25+
## Link the Log Analytics workspace to the Managed CCF resource
26+
27+
1. After the workspace is created, it must be linked with the Managed CCF resource. It takes a few minutes after linking for the logs to appear in the workspace.
28+
29+
```azurecli
30+
> az login
31+
32+
> az monitor diagnostic-settings create --name confidentialbillingapplogs --resource <Resource Id of the Managed CCF resource> --workspace <Resource Id of the workspace> --logs [{\"category\":\"applicationlogs\",\"enabled\":true,\"retentionPolicy\":{\"enabled\":false,\"days\":0}}]
33+
```
34+
1. Open the Logs page. Navigate to the Queries tab and group the queries by Resource type from the drop-down. Navigate to the 'Azure Managed CCF' resource and run the 'CCF application errors' query. Remove the 'Level' filter to view all the logs.
35+
36+
:::image type="content" source="media/how-to/log-analytics-logs.png" alt-text="Screenshot that shows the Managed CCF resource query in the Log Analytics screen.":::
37+
38+
## Next steps
39+
40+
- [Azure Managed CCF overview](overview.md)
41+
- [Quickstart: Deploy an Azure Managed CCF application](quickstart-deploy-application.md)

‎articles/managed-ccf/how-to-manage-members.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Quickstart – Add and remove members from a Microsoft Azure Managed CCF resource
3+
description: Learn to manage the members from a Microsoft Azure Managed CCF resource
4+
author: msftsettiy
5+
ms.author: settiy
6+
ms.date: 09/10/2023
7+
ms.service: confidential-ledger
8+
ms.topic: how-to
9+
---
10+
11+
# Add and remove members from an Azure Managed CCF resource
12+
13+
Members can be added and removed from an Azure Managed CCF (Managed CCF) resource using governance operations. This tutorial builds on the Managed CCF resource created in the [Quickstart: Create an Azure Managed CCF resource using the Azure portal](quickstart-portal.md) tutorial.
14+
15+
## Prerequisites
16+
17+
[!INCLUDE [Prerequisites](./includes/proposal-prerequisites.md)]
18+
19+
## Download the service identity
20+
21+
[!INCLUDE [Download Service Identity](./includes/service-identity.md)]
22+
23+
[!INCLUDE [Mac instructions](./includes/macos-instructions.md)]
24+
25+
## Add a member
26+
27+
[!INCLUDE [Create a member identity](./includes/create-member.md)]
28+
29+
1. Submit a proposal to add the member.
30+
```bash
31+
$cat set_member.json
32+
{
33+
"actions": [
34+
{
35+
"name": "set_member",
36+
"args": {
37+
"cert": "-----BEGIN CERTIFICATE-----\nMIIBtDCCATqgAwIBAgIUV...sy93h74oqHk=\n-----END CERTIFICATE-----",
38+
"encryption_pub_key": ""
39+
}
40+
}
41+
]
42+
}
43+
44+
$ proposal_id=$( (ccf_cose_sign1 --content set_member.json --signing-cert member0_cert.pem --signing-key member0_privk.pem --ccf-gov-msg-type proposal --ccf-gov-msg-created_at `date -Is` | curl https://confidentialbillingapp.confidential-ledger.azure.com/gov/proposals -H 'Content-Type: application/cose' --data-binary @- --cacert service_cert.pem) )
45+
```
46+
1. Accept the proposal by submitting a vote. Repeat the step for all the members in the resource.
47+
[!INCLUDE [Submit a vote](./includes/submit-vote.md)]
48+
1. When the command completes, the member is added in the Managed CCF resource. But, they cannot participate in the governance operations unless they are activated. Refer to the quickstart tutorial [Activate a member](how-to-activate-members.md) to activate the member.
49+
1. View the members in the network using the following command.
50+
51+
[!INCLUDE [View members](./includes/view-members.md)]
52+
53+
## Remove a member
54+
55+
1. Submit a proposal to remove the member. The member is identified by their public certificate.
56+
```bash
57+
$cat remove_member.json
58+
{
59+
"actions": [
60+
{
61+
"name": "remove_member",
62+
"args": {
63+
"cert": "-----BEGIN CERTIFICATE-----\nMIIBtDCCATqgAwIBAgIUV...sy93h74oqHk=\n-----END CERTIFICATE-----",
64+
}
65+
}
66+
]
67+
}
68+
69+
$ proposal_id=$( (ccf_cose_sign1 --content remove_member.json --signing-cert member0_cert.pem --signing-key member0_privk.pem --ccf-gov-msg-type proposal --ccf-gov-msg-created_at `date -Is` | curl https://confidentialbillingapp.confidential-ledger.azure.com/gov/proposals -H 'Content-Type: application/cose' --data-binary @- --cacert service_cert.pem) )
70+
```
71+
2. Accept the proposal by submitting a vote. Repeat the step for all the members in the resource.
72+
[!INCLUDE [Submit a vote](./includes/submit-vote.md)]
73+
3. When the command completes, the member is removed from the Managed CCF resource and they can no longer participate in the governance operations.
74+
4. View the members in the network using the following command.
75+
76+
[!INCLUDE [View members](./includes/view-members.md)]
77+
78+
## Next steps
79+
80+
- [Microsoft Azure Managed CCF overview](overview.md)
81+
- [Quickstart: Deploy an Azure Managed CCF application](quickstart-deploy-application.md)
82+
- [How to: Activate members](how-to-activate-members.md)

‎articles/managed-ccf/how-to-update-application.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Quickstart – Update the JavaScript application on a Microsoft Azure Managed CCF resource
3+
description: Learn to update the JavaScript application on a Microsoft Azure Managed CCF resource
4+
author: msftsettiy
5+
ms.author: settiy
6+
ms.date: 09/10/2023
7+
ms.service: confidential-ledger
8+
ms.topic: how-to
9+
---
10+
11+
# Quickstart: Update the JavaScript application
12+
13+
With Azure Managed CCF (Managed CCF), it is simple and quick to update an application when new functionality is introduced or when bugs fixes are available. This tutorial builds on the Managed CCF resource created in the [Quickstart: Create an Azure Managed CCF resource using the Azure portal](quickstart-portal.md) tutorial.
14+
15+
## Prerequisites
16+
17+
[!INCLUDE [Prerequisites](./includes/proposal-prerequisites.md)]
18+
19+
## Download the service identity
20+
21+
[!INCLUDE [Download Service Identity](./includes/service-identity.md)]
22+
23+
## Update the application
24+
25+
[!INCLUDE [Mac instructions](./includes/macos-instructions.md)]
26+
27+
> [!NOTE]
28+
> This tutorial assumes that the updated application bundle is created using the instructions available [here](https://microsoft.github.io/CCF/main/build_apps/js_app_bundle.html) and saved to set_js_app.json.
29+
>
30+
> Updating an application does not reset the JavaScript runtime options.
31+
32+
[!INCLUDE [Deploy an application](./includes/deploy-update-application.md)]
33+
34+
When the command completes, the application will be updated and ready to accept user transactions.
35+
36+
## Next steps
37+
38+
- [Microsoft Azure Managed CCF overview](overview.md)
39+
- [How to: View application logs in Azure Monitor](how-to-enable-azure-monitor.md)
40+
- [Quickstart: Deploy an Azure Managed CCF application](quickstart-deploy-application.md)

0 commit comments

Comments
 (0)