Set up the agent for SAP workloads

Workload Manager for SAP solutions uses Google Cloud's Agent for SAP to detect and collect metadata for evaluating your SAP system configurations. The Agent for SAP, along with the SAP Host Agent, are required on all VM instances that run SAP systems for support and monitoring of your SAP systems running on Google Cloud, including SAP NetWeaver, SAP HANA, SAP ASE, and SAP MaxDB.

Before you begin

Before you install and configure Google Cloud's Agent for SAP, you need to make sure that the following prerequisites are met:

Required IAM roles for the agent

Agent for SAP uses the service account attached to the compute instance for authentication and to access Google Cloud resources.

To improve security, we recommend that you use a single-purpose service account rather than using the Compute Engine default service account.

To ensure that the service account has the necessary permissions to let Agent for SAP authenticate with Google Cloud and access Google Cloud resources, ask your administrator to grant the following IAM roles to the service account on your project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give the service account the required permissions through custom roles or other predefined roles.

Enable access to Cloud APIs

Compute Engine recommends configuring your instances to allow all access scopes to all Cloud APIs. To control access to Google Cloud resources, use only the IAM permissions of the instance service account. For more information, see Create a VM that uses a user-managed service account.

If you limit access to the Cloud APIs, then the Agent for SAP requires at minimum the following Cloud APIs access scopes on the host compute instance:

https://www.googleapis.com/auth/cloud-platform

For more information, see Scopes best practice.

If you're running SAP applications on a compute instance that doesn't have an external IP address, then you need to enable Private Google Access on the instance's subnet so that Agent for Compute Workloads can access the Google APIs and services. For information about how to enable Private Google Access, see Configure Private Google Access.

Install and configure the agent by using package manager

This section shows you how to install the Agent for SAP on your compute instance, and configure it to connect with your SAP workload, by using a package manager.

If you want to install and configure the agent on a fleet of VMs, then you can use a VM Extension Manager policy instead. For more information, see Install and manage the agent on a fleet of VMs by using VM Extension Manager.

Install the agent

If not already done, then install Google Cloud's Agent for SAP on all compute instances that run your SAP workload:

To install the agent on a Compute Engine instance, follow these steps:

  1. Establish an SSH connection to your compute instance.
  2. In your terminal, install the agent by running the command that is specific to your operating system:
    • (Recommended) To install version 3.13 (latest) of the agent:

      RHEL

      sudo tee /etc/yum.repos.d/google-cloud-sap-agent.repo << EOM
[google-cloud-sap-agent]
name=Google Cloud Agent for SAP
baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-el$(cat /etc/redhat-release | cut -d . -f 1 | tr -d -c 0-9)-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM
sudo yum install google-cloud-sap-agent

      SLES15

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles15-x86_64 google-cloud-sap-agent
sudo zypper install google-cloud-sap-agent

      SLES 12

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles12-x86_64 google-cloud-sap-agent
sudo zypper install google-cloud-sap-agent
    • To install a specific version of the agent:

      RHEL

      sudo tee /etc/yum.repos.d/google-cloud-sap-agent.repo << EOM
[google-cloud-sap-agent]
name=Google Cloud Agent for SAP
baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-el$(cat /etc/redhat-release | cut -d . -f 1 | tr -d -c 0-9)-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM
sudo yum install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      SLES15

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles15-x86_64 google-cloud-sap-agent
sudo zypper install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      SLES 12

      sudo zypper addrepo --refresh https://packages.cloud.google.com/yum/repos/google-cloud-sap-agent-sles12-x86_64 google-cloud-sap-agent
sudo zypper install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      Replace VERSION_NUMBER with the agent's version number that you want to install, such as 3.1-606637668. For information about the agent versions that you can install, see List all available versions of the agent.

      For information about downgrading the agent to a specific version, see Downgrade Google Cloud's Agent for SAP.

Configure the collection of Workload Manager evaluation metrics

After you install Agent for SAP, you need to configure the agent for the collection of the Workload Manager evaluation metrics.

To configure Google Cloud's Agent for SAP, complete the following steps:

  1. To let the agent collect the Workload Manager evaluation metrics:

    sudo /usr/bin/google_cloud_sap_agent configure -feature=workload_evaluation -enable

  2. Optional: To enable the collection of "SAP HANA Insights" and "SAP HANA Security Best Practices" metrics in Workload Manager, add the workload_validation_db_metrics_config section after collect_workload_validation_metrics in the agent's configuration file, and then specify the following parameters:

    • hana_db_user: specify the user account that is used to query the SAP HANA instance.
    • hostname: specify the identifier for the machine, either local or remote, that hosts your SAP HANA instance.
    • port: specify the port on which your SAP HANA instance accepts queries.

    • hana_db_password_secret_name: specify the name of the secret in Secret Manager that stores the user account's password

      As an alternative to the secret, you can use the hdbuserstore_key configuration parameter.

    • hdbuserstore_key: specify the hdbuserstore key that authenticates the user you specified for hana_db_user

      If you specify hdbuserstore_key, then you skip specifying the hostname and port parameters.

    For information about these parameters, see Configuration parameters.

    The following examples are completed configuration files of Google Cloud's Agent for SAP running on a Compute Engine instance, where the collection of Workload Manager evaluation metrics is enabled.

    For SAP HANA authentication, the agent uses the following order of preference: if specified, the hdbuserstore_key configuration parameter is preferred over the hana_db_password parameter, which is preferred over the hana_db_password_secret_name parameter. We recommend that you set only one authentication option in your configuration file.

    • The following example uses a Secure user store (hdbuserstore) key for SAP HANA authentication: 
      {
  "provide_sap_host_agent_metrics": true,
  "bare_metal": false,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": true,
    "workload_validation_db_metrics_frequency": 3600,
    "workload_validation_db_metrics_config": {
      "hana_db_user": "system",
      "sid": "DEH",
      "hdbuserstore_key": "user_store_key"
    },
    "collect_process_metrics": false
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": false
  }
}
    • The following example uses a username and Secret Manager secret for SAP HANA authentication: 
      {
  "provide_sap_host_agent_metrics": true,
  "bare_metal": false,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": true,
    "workload_validation_db_metrics_frequency": 3600,
    "workload_validation_db_metrics_config": {
      "hana_db_user": "system",
      "sid": "DEH",
      "hana_db_password_secret_name": "instance-id-hana-db-password-secret",
      "hostname": "localhost",
      "port": "30015"
    },
    "collect_process_metrics": false
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": false
  }
}
    • The following example uses a username and password for SAP HANA authentication. We recommend that you instead use a Secret Manager secret or Secure user store (hdbuserstore) key for SAP HANA authentication. 
      {
  "provide_sap_host_agent_metrics": true,
  "bare_metal": false,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": true,
    "workload_validation_db_metrics_frequency": 3600,
    "workload_validation_db_metrics_config": {
      "hana_db_user": "system",
      "sid": "DEH",
      "hana_db_password": "TempPa55word",
      "hostname": "localhost",
      "port": "30015"
    },
    "collect_process_metrics": false
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": false
  }
}

  3. Restart the agent for the new settings to take effect:

    sudo systemctl restart google-cloud-sap-agent

    After the agent successfully restarts, the agent starts sending the Workload Manager evaluation metrics to Workload Manager.

Install and manage the agent on a fleet of VMs by using VM Extension Manager

This section shows you how to install and manage the Agent for SAP on a fleet of VMs by using VM Extension Manager.

Set up VM Extension Manager

To set up VM Extension Manager, complete the following steps:

Install and configure the agent on a fleet of VMs

To install the latest version of Agent for SAP on your VM fleet within a specific zone by using a VM Extension Manager policy, complete the following steps:

Console

  1. In the Google Cloud console, go to the VM extension policies page.

    Go to VM extension policies

  2. Click Create extension policy.

  3. In the Name field, enter a name for the policy.

  4. Optional: In the Description field, enter a description for the policy.

  5. In the Priority field, specify a priority number to resolve conflicts between policies. Lower numbers indicate higher priority. The default value is 1000.

  6. Using the Region and Zone lists, select the zone where you want to apply this policy.

  7. In the Extensions section, click Add extension and then do the following:

    1. From the Extension list, select Google Cloud's Extension for Compute Workloads.

    2. Leave the Version field blank.

      This directs the policy to install the latest version of Google Cloud's Agent for SAP.

    3. In the Configuration file content field, enter the configuration that you want to apply to the agent.

      For information about the configuration parameters supported by the agent for your SAP workload, see Configuration parameters.

    4. Click Done.

  8. Optional: To limit the policy rollout to the required VMs, do the following:

    1. Click Add labels and include the labels that identify the required VMs.
    2. Click Done.

  9. Click Create.

gcloud 

gcloud compute zone-vm-extension-policies create POLICY_NAME \
    --zone=ZONE \
    --extensions=google-cloud-sap-extension \
    --config-from-file=google-cloud-sap-extension=CONFIG_FILE_PATH \
    [--description="DESCRIPTION" \]
    [--inclusion-labels=KEY_1=VALUE_1 \]
    [--inclusion-labels=KEY_2=VALUE_2,KEY_3=VALUE_3 \]
    [--priority=PRIORITY]

Replace the following:

  • POLICY_NAME: a name for the VM extension policy.

    The command fails if a policy with the specified name already exists in the zone.

  • ZONE: the zone where you want to apply this policy.

  • CONFIG_FILE_PATH: the local path to the JSON file that contains the configuration for the Agent for SAP to connect with your SAP workload.

    • Alternatively, to provide configuration as an inline string, use the --config flag instead of --config-from-file. For example, --config=google-cloud-sap-extension="CONFIG". Google Cloud recommends that you use --config-from-file.
    • You can use either --config-from-file or --config, but not both in the same command.
    • For information about the configuration parameters supported by the agent for your SAP workload, see Configuration parameters.

  • DESCRIPTION: an optional description for the policy.

  • KEY_1=VALUE_1: a comma-separated list of key-value pairs that define the labels using which the policy targets VMs.

    • For a VM to be targeted by your policy, the VM must have all the specified labels.
    • If you specify --inclusion-labels multiple times, then the policy targets VMs that match any of the provided selectors (logical OR). If you omit this flag, then the policy targets all VMs in the specified zone.

  • PRIORITY: an integer from 0 to 65535 that defines the policy's priority. Lower numbers indicate higher priority. The default value is 1000.

Example:

The following command creates a policy named test-agent-policy in the Google Cloud project named test-project, which installs the latest version of Agent for Compute Workloads on all VMs deployed in the zone us-centrail-f. The configuration specified in the agent-config.json is applied to the agent.

gcloud compute zone-vm-extension-policies create test-agent-policy  \
    --project=test-project \
    --zone=us-central1-f \
    --extensions=google-cloud-sap-extension \
    --config-from-file=google-cloud-sap-extension="/usr/agent-config.json"

Verify the agent version

Google Cloud recommends that you install the latest version of Agent for SAP for accurate evaluation of your SAP workloads because periodic releases of the Agent for SAP might add or change metrics that are used for the evaluation.

To ensure that you have the latest version of Google Cloud's Agent for SAP, you need to check for updates periodically and update the agent.

Check for updates

Select your operating system, and then follow these steps:

RHEL

  1. Establish an SSH connection with your instance.
  2. Run the following command: 
    sudo yum check-update google-cloud-sap-agent

SLES

  1. Establish an SSH connection with your instance.
  2. Run the following command: 
    sudo zypper list-updates -r google-cloud-sap-agent

Install an update

Select your operating system, and then follow the steps:

RHEL

  1. Establish an SSH connection with your instance.
  2. Update your agent instance:
    • (Recommended) To update to version 3.13 (latest) of the agent: 
      sudo yum --nogpgcheck update google-cloud-sap-agent
    • To update to a specific version of the agent: 
      sudo yum install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      Replace VERSION_NUMBER with the agent's version number that you want to install, such as 3.1-606637668. For information about the agent versions that you can install, see List all available versions of the agent.

SLES

  1. Establish an SSH connection with your instance.
  2. Update your agent instance:
    • (Recommended) To update to version 3.13 (latest) of the agent: 
      sudo zypper --no-gpg-checks update google-cloud-sap-agent
    • To update to a specific version of the agent: 
      sudo zypper install google-cloud-sap-agent-VERSION_NUMBER.x86_64

      Replace VERSION_NUMBER with the agent's version number that you want to install, such as 3.1-606637668. For information about the agent versions that you can install, see List all available versions of the agent.

Validate the setup for Workload Manager evaluation metrics collection

You can validate if you have the correct Google Cloud setup for the collection of the Workload Manager evaluation metrics by running the agent's status command. This command is supported from version 3.7 of the agent.

To validate the Google Cloud setup, complete the following steps:

  1. Establish an SSH connection with your Compute Engine instance.
  2. Run the following command: 
    sudo /usr/bin/google_cloud_sap_agent status -f="workload_manager,sap_discovery"

    If your Google Cloud setup for Workload Manager evaluation metrics collection is correct, then the output includes the following. Your configuration might have values other than the default ones.

        Agent Status:
        ...
        Systemd Service Enabled: True
        Systemd Service Running: True
        Cloud API Full Scopes: True
        Configuration File: /etc/google-cloud-sap-agent/configuration.json
        Configuration Valid: True
    ...
    ----------------------------------------------------------------------------
    System Discovery: Enabled
        Status: Fully Functional
        IAM Permissions: All granted
        Configuration:
            enable_discovery:                  true  (default)
            enable_workload_discovery:         true  (default)
            sap_instances_update_frequency:    60    (default)
            system_discovery_update_frequency: 14400 (default)
    ----------------------------------------------------------------------------
    Workload Manager Evaluation: Enabled
        Status: Fully Functional
        IAM Permissions: All granted
        Configuration:
            collect_workload_validation_metrics:      true       (default)
            config_target_environment:                PRODUCTION (default)
            fetch_latest_config:                      true       (default)
            workload_validation_db_metrics_frequency: 3600       (default)
            workload_validation_metrics_frequency:    300        (default)
    ...
  3. If your output conveys that some setup is missing, then review the information provided in the preceding sections, perform the required actions, and then re-run the status command to re-validate the setup.

Example configuration file

The following examples are completed configuration files of Google Cloud's Agent for SAP running on a Compute Engine instance, where the collection of Workload Manager evaluation metrics is enabled.

For SAP HANA authentication, the agent uses the following order of preference: if specified, the hdbuserstore_key configuration parameter is preferred over the hana_db_password parameter, which is preferred over the hana_db_password_secret_name parameter. We recommend that you set only one authentication option in your configuration file.

  • The following example uses a Secure user store (hdbuserstore) key for SAP HANA authentication: 
    {
  "provide_sap_host_agent_metrics": true,
  "bare_metal": false,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": true,
    "workload_validation_db_metrics_frequency": 3600,
    "workload_validation_db_metrics_config": {
      "hana_db_user": "system",
      "sid": "DEH",
      "hdbuserstore_key": "user_store_key"
    },
    "collect_process_metrics": false
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": false
  }
}
  • The following example uses a username and Secret Manager secret for SAP HANA authentication: 
    {
  "provide_sap_host_agent_metrics": true,
  "bare_metal": false,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": true,
    "workload_validation_db_metrics_frequency": 3600,
    "workload_validation_db_metrics_config": {
      "hana_db_user": "system",
      "sid": "DEH",
      "hana_db_password_secret_name": "instance-id-hana-db-password-secret",
      "hostname": "localhost",
      "port": "30015"
    },
    "collect_process_metrics": false
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": false
  }
}
  • The following example uses a username and password for SAP HANA authentication. We recommend that you instead use a Secret Manager secret or Secure user store (hdbuserstore) key for SAP HANA authentication. 
    {
  "provide_sap_host_agent_metrics": true,
  "bare_metal": false,
  "log_level": "INFO",
  "log_to_cloud": true,
  "collection_configuration": {
    "collect_workload_validation_metrics": true,
    "workload_validation_db_metrics_frequency": 3600,
    "workload_validation_db_metrics_config": {
      "hana_db_user": "system",
      "sid": "DEH",
      "hana_db_password": "TempPa55word",
      "hostname": "localhost",
      "port": "30015"
    },
    "collect_process_metrics": false
  },
  "discovery_configuration": {
    "enable_discovery": true,
    "enable_workload_discovery": true
  },
  "hana_monitoring_configuration": {
    "enabled": false
  }
}

For information about the configuration parameters that are supported by Agent for SAP, see Configuration parameters.

What's next