Skip to content

Commit

Permalink
Update Backup and DR.md
Browse files Browse the repository at this point in the history 
minor typos
  • Loading branch information
@jeffoconnorau
jeffoconnorau committed Mar 12, 2024
1 parent bce089f commit 0fdd395
Showing 1 changed file with 27 additions and 27 deletions.
54 changes: 27 additions & 27 deletions Backup and DR.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Management Console API Examples
This document describes how to configure REST API access to the Google Cloud Backup and DR Management Console. This document will also provide guidance if you are converting from Actifio GO
This document describes how to configure REST API access to the Google Cloud Backup and DR Management Console. This document will also provide guidance if you are converting from Actifio GO

## Prerequisites
To perform Google Cloud Backup and DR REST API operations, you need the following:
Expand All @@ -9,28 +9,28 @@ To perform Google Cloud Backup and DR REST API operations, you need the followin
1. A Linux or Windows Compute Engine Instance which has a service account attached that can get generate tokens and which has GCloud CLI and PowerShell installed.
1. A Linux, Mac or Windows host which has GCloud CLI installed and which has a downloaded JSON key for the relevant service account.

> **Note**: The host running this script needs access to the internet. The Management Console cannot be accessed via private connect. So for a Compute Engine instance this means it needs either an external IP or a Cloud Router/NAT setup.
> **Note**: The host running this script needs access to the internet. The Management Console cannot be accessed via private connect. So for a Compute Engine instance this means it needs either an external IP or a Cloud Router/NAT setup.
## Getting Management Console details

Once you have deployed Backup and DR, then a management console will be configured. It is useful to know the project that your management console is peered to and the region where it was deployed. Open the Show API Credentials twisty to learn the Management Console API URL and OAuth 2.0 client ID. You will need these.
Once you have deployed Backup and DR, then a management console will be configured. It is useful to know the project that your management console is peered to and the region where it was deployed. Open the Show API Credentials twisty to learn the Management Console API URL and OAuth 2.0 client ID. You will need these.

In this example (yours will be different!):

* Management Console URL: https://agm-666993295923.backupdr.actifiogo.com/actifio
* OAuth 2.0 client ID: 486522031570-fimdb0rbeamc17l3akilvquok1dssn6t.apps.googleusercontent.com
* Management Console URL: https://bmc-676825165455-jcohvzto-dot-asia-southeast1.backupdr.googleusercontent.com/actifio
* OAuth 2.0 client ID: 486521251570-fimdb0rbeamc17l3akilvquok1dssn6t.apps.googleusercontent.com


## Creating your Service Account

From Cloud Console IAM & Admin panel in the project where Backup and DR was activated, go to **Service Account** and choose **Create Service Account**. You can also modify an existing one if desired.
From Cloud Console IAM & Admin panel in the project where Backup and DR was activated, go to **Service Account** and choose **Create Service Account**. You can also modify an existing one if desired.

Ensure it has **one** of the two following roles:

* ```Backup and DR User```
* ```Backup and DR Admin```

You then need to go to **IAM & Admin** > **Service Accounts**. Find that service account, select it, go to **PERMISSIONS,** select **GRANT ACCESS**, enter the principal (email address) of the service account we will activate or attach with one of the following roles (you don't need both). You can assign this to the same service account that was assigned the ```Backup and DR``` role:
You then need to go to **IAM & Admin** > **Service Accounts**. Find that service account, select it, go to **PERMISSIONS,** select **GRANT ACCESS**, enter the principal (email address) of the service account we will activate or attach with one of the following roles (you don't need both). You can assign this to the same service account that was assigned the ```Backup and DR``` role:

* ```Service Account Token Creator```
* ```Service Account OpenID Connect Identity Token Creator```
Expand All @@ -40,13 +40,13 @@ You then need to go to **IAM & Admin** > **Service Accounts**. Find that servic
Decide where/how you will run your service account. You have two options:
1. Compute Engine Instance with attached service account

In option 1 we are going to use a Compute Engine instance to run our API commands/automation and because a Compute Engine Instance can have an attached Service Account, we can avoid the need to install a service key on that host. The host needs the GCloud CLI installed (which is automatic if you use a Google image to create the instance).
In option 1 we are going to use a Compute Engine instance to run our API commands/automation and because a Compute Engine Instance can have an attached Service Account, we can avoid the need to install a service key on that host. The host needs the GCloud CLI installed (which is automatic if you use a Google image to create the instance).

In your project create or select an instance that you want to use for API operations. Ensure the service account that is attached to the instance has the permissions detailed above. You can use an existing instance or create a new one. If you need to change/set the Service Account, the instance needs to be powered off.
In your project create or select an instance that you want to use for API operations. Ensure the service account that is attached to the instance has the permissions detailed above. You can use an existing instance or create a new one. If you need to change/set the Service Account, the instance needs to be powered off.

2. Activate your service account on a host

In option 2, we are going to use a Compute Engine instance or external host/VM to run our API commands/automation, but we are going to 'activate' the Service account using a JSON Key. The host needs the **gcloud** CLI installed.
In option 2, we are going to use a Compute Engine instance or external host/VM to run our API commands/automation, but we are going to 'activate' the Service account using a JSON Key. The host needs the **gcloud** CLI installed.

We need to activate our service account since we are not executing this command from a Compute Engine instance with an attached service account.
So firstly we need to download a JSON key from the Google Cloud Console and copy that key to our relevant host:
Expand Down Expand Up @@ -103,9 +103,9 @@ $ curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-
}
```
### Add the user before they login
To ensure the user has the correct role the first time it logs in, manually adding the user to the Management Console BEFORE the first login is recommended. After you create the user in Google IAM, login to your Management Console, go to Manage → Users and select Create User
To ensure the user has the correct role the first time it logs in, manually adding the user to the Management Console BEFORE the first login is recommended. After you create the user in Google IAM, login to your Management Console, go to Manage → Users and select Create User

Now enter the Service account email as the Username and select the relevant roles.
Now enter the Service account email as the Username and select the relevant roles.

You can now proceed to login having 'pre-added' user and assigned it a Management Console role.

Expand All @@ -122,19 +122,19 @@ Modify this command to change the service account and the oauth2ClientId
```
curl -sS -XPOST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[email protected]:generateIdToken -d '{"audience":"486522031570-fimdb0rbeamc17l3akilvquok1dssn6t.apps.googleusercontent.com", "includeEmail":"true"}'
```
This command will create a token. Place that token into a variable called $TOKEN
This command will create a token. Place that token into a variable called $TOKEN
To use JQ to do this:
```
TOKEN=$(curl -sS -XPOST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[email protected]:generateIdToken -d '{"audience":"486522031570-fimdb0rbeamc17l3akilvquok1dssn6t.apps.googleusercontent.com", "includeEmail":"true"}' | jq -r '.token')
```

#### Step two - create a session ID

Now we have a $TOKEN we then create a session ID with the following command. Again you need to modify this example to set your Management Console API endpoint. Note it needs /session at the end.
Now we have a $TOKEN we then create a session ID with the following command. Again you need to modify this example to set your Management Console API endpoint. Note it needs /session at the end.
```
curl -sS -XPOST -H "Authorization: Bearer $TOKEN" -H "Content-Length: 0" https://agm-666993295923.backupdr.actifiogo.com/actifio/session
```
The first part of the output should contain a section like this. The session_id is needed for all future commands.
The first part of the output should contain a section like this. The session_id is needed for all future commands.
```
"@type" : "sessionRest",
"id" : "4653d447-c8f3-4ac1-af65-2816363355e0",
Expand All @@ -147,7 +147,7 @@ Here is an example with JQ:
```
SESSIONID=$(curl -sS -XPOST -H "Authorization: Bearer $TOKEN" -H "Content-Length: 0" https://agm-666993295923.backupdr.actifiogo.com/actifio/session | jq -r '.id')
```
Now modify this command to validate your connection. Change the API endpoint. It needs /config/version at the end.
Now modify this command to validate your connection. Change the API endpoint. It needs /config/version at the end.
```
curl -H "Authorization: Bearer $TOKEN" -H "backupdr-management-session: Actifio $SESSIONID" https://agm-666993295923.backupdr.actifiogo.com/actifio/config/version
```
Expand All @@ -162,7 +162,7 @@ Here is an example:

#### Example script

In this example script, you need to modify the BMCNAME, SANAME and OAUTH to match yours. This script literally just reports the version of the Management Console:
In this example script, you need to modify the BMCNAME, SANAME and OAUTH to match yours. This script literally just reports the version of the Management Console:
```
#!/bin/bash
# UPDATE THESE THREE VALUES TO MATCH YOUR ENVIRONMENT
Expand All @@ -177,7 +177,7 @@ VERSION=$(curl -sS -H "Authorization: Bearer $TOKEN" -H "backupdr-management-ses
# echo data
echo $VERSION
```
In this sample script we simplify things. Because the activated service account is the same account we login to the Management Console with, we don't need to supply. We instead learn it:
In this sample script we simplify things. Because the activated service account is the same account we login to the Management Console with, we don't need to supply. We instead learn it:
```
#!/bin/bash
# UPDATE THESE TWO VALUES TO MATCH YOUR ENVIRONMENT
Expand Down Expand Up @@ -218,7 +218,7 @@ We now have the application ID for our application (in this example 8766).

### Learning the policy ID

This is done in two parts. First we need to learn the template (SLT) ID. So use your application ID like this:
This is done in two parts. First we need to learn the template (SLT) ID. So use your application ID like this:
```
appid=1482152
curl -sS -X GET -H "Content-type: application/json" -H "Authorization: Bearer $TOKEN" -H "backupdr-management-session: Actifio $SESSIONID" "https://$BMCNAME/actifio/sla?filter=appid:==$appid" | jq -cr '.items[] | [.slt]'
Expand All @@ -240,7 +240,7 @@ Here is an example of the output, where the ID of our policy in this example is
```
### Run the on demand backup

Now we have the appid and policy ID we can run the backup job. Importantly we also need to add a label. While a label is not mandatory it makes finding the job much easier. Use a unique label for each job.
Now we have the appid and policy ID we can run the backup job. Importantly we also need to add a label. While a label is not mandatory it makes finding the job much easier. Use a unique label for each job.

```
appid=1482152
Expand All @@ -257,7 +257,7 @@ label="test1"
curl -w "\n" -sS -XPOST -H "Content-type: application/json" -H "Authorization: Bearer $TOKEN" -H "backupdr-management-session: Actifio $SESSIONID" "https://$BMCNAME/actifio/application/$appid/backup" -d "{\"policy\":{\"id\":$policyid},\"backuptype\":\"$backuptype\",\"label\":\"$label\"}"
```
### Track the running job
To find running jobs use this command. Remember we are using a label since without a label it is complex to find the job status.
To find running jobs use this command. Remember we are using a label since without a label it is complex to find the job status.
```
curl -sS -X GET -H "Content-type: application/json" -H "Authorization: Bearer $TOKEN" -H "backupdr-management-session: Actifio $SESSIONID" "https://$BMCNAME/actifio/jobstatus?filter=label:==$label" | jq -cr '.items[] | [.jobname, .appname, .status, .progress]'
```
Expand All @@ -282,29 +282,29 @@ Let's look at each point:

### AGM API vs Sky API

Backup and DR only supports AGM API commands, sent to the Management Console. If your automation is targeting a Sky Appliance using udsinfo and udstask commands sent either via ActPowerCLI (PowerShell), REST API command or an SSH session, then it cannot be used with Backup and DR and will need to be re-written. If your automation is already using AGM API commands (or AGMPowerCLI), then very few changes will be needed.
Backup and DR only supports AGM API commands, sent to the Management Console. If your automation is targeting a Sky Appliance using udsinfo and udstask commands sent either via ActPowerCLI (PowerShell), REST API command or an SSH session, then it cannot be used with Backup and DR and will need to be re-written. If your automation is already using AGM API commands (or AGMPowerCLI), then very few changes will be needed.

### Automation Host Configuration

The automation host for Backup and DR API calls will need the gcloud CLI installed. Once installed the gcloud CLI will need access to a Google Cloud Service Account (with the correct roles), either through being executed on a GCE Instance running as that SA, or by using an activated JSON key for that service account. The setup tasks for this typically only need to be done once, and are detailed in the sections above.
The automation host for Backup and DR API calls will need the gcloud CLI installed. Once installed the gcloud CLI will need access to a Google Cloud Service Account (with the correct roles), either through being executed on a GCE Instance running as that SA, or by using an activated JSON key for that service account. The setup tasks for this typically only need to be done once, and are detailed in the sections above.

If using JSON keys, and the JSON keys expire, then a process to renew the keys will need to be established.

## FAQ
### I can connect but don't seem to stay connected

The issue is that your Management Console user has no role. Go to the Management Console GUI and set the Users role. Then create a new token and session.
The issue is that your Management Console user has no role. Go to the Management Console GUI and set the Users role. Then create a new token and session.

### Can I use this Service Account to login to the Management Console WEB GUI?

No you cannot. A service account cannot be used to login to a Web Browser to authorize Console access
No you cannot. A service account cannot be used to login to a Web Browser to authorize Console access

### Can I use one service account into two projects?

Let's say we have two projects, ProjectA and ProjectB:

1. You activate Google Cloud Back and DR in both projects.
1. You create a service account api@saprojectA in projectA and give it the roles/permissions needed to perform API operations in ProjectA
1. You activate Google Cloud Back and DR in both projects.
1. You create a service account api@saprojectA in projectA and give it the roles/permissions needed to perform API operations in ProjectA
1. You can now add api@saprojectA to project B and provided you give it the same role/permissions it can now do API operations in both ProjectA and ProjectB

The one thing you cannot do is run an instance in ProjectB as the SA from ProjectA using Option 2: Activate your service account on a host

0 comments on commit 0fdd395

Please sign in to comment.