Enabling the Block Volume Management Plugin
Enable the Block Volume Management plugin on a Compute instance.
The Block Volume Management plugin is required for the following volume attachment scenarios:
iSCSI attached volumes configured for the Ultra High Performance level. These volume attachements need to be multipath-enabled to achieve the optimized performance available with the Ultra High Performance level.
iSCSI attached volumes configured for other performance levels and configured to automatically connect. These volumes were attached with the Use Oracle Cloud Agent to automatically connect to iSCSI-attached volumes option selected, and is supported for attachments to Linux and Windows-based instances. The following table lists the available version of the Oracle Cloud Agent software for the different operating systems:
Operating systems and corresponding Oracle Cloud Agent versions OS Oracle Cloud Agent version Oracle Linux or a custom image based on an Oracle Linux image 1.23.0 or newer Windows or a custom image based on a Windows image 1.24.0 or newer Ubuntu or a custom image based on an Ubuntu image 1.35.0 or newer
The Block Volume Management plugin is managed by the Oracle Cloud Agent software and performs the following actions:
Checks the instance's metadata for multipath-enabled attachments to Ultra High Performance volumes or attachments configured to automatically connect to volumes configured for other performance levels, with a polling interval of one minute.
Installs
device-mapper-multipath rpmand adds"/etc/multipath.conf"only if there are multipath-enabled attachments.If there are multipath-enabled attachments or attachments configured to automatically connect in the instance's metadata, then the plugin performs batch iSCSI
logincommands for the volume attachments.
Prerequisites
The Block Volume Management plugin is supported on Oracle Autonomous Linux and Oracle Linux images, and on custom images that are based on those images.
The following steps are required for the Block Volume Management plugin.
-
Service gateways or public IP addresses: The compute instance must have either a public IP address or a service gateway to be able to connect to Oracle services.
If the instance does not have a public IP address, set up a service gateway on the virtual cloud network (VCN). The service gateway lets your instance privately access Oracle services without exposing the data to the public internet. Here are special notes for setting up the service gateway for the Block Volume Management plugin:
- When creating the service gateway, enable the service label called All <region> Services in Oracle Services Network.
- When setting up routing for the subnet that contains the instance, set up a route rule with Target Type set to Service Gateway, and the Destination Service set to All <region> Services in Oracle Services Network.
For detailed instructions, see Access to Oracle Services: Service Gateway.
- Oracle Cloud Agent: The Oracle Cloud Agent software must be installed on the instance. Oracle Cloud Agent is installed by default on current platform images. For steps to manually install Oracle Cloud Agent on older images, see Installing the Oracle Cloud Agent Software. To update, see Updating the Oracle Cloud Agent Software. Important
If you're enabling the Block Volume Management plugin to support the automatically connect to a volume scenario, the instance must be running version 1.23.0 or newer of the Oracle Cloud Agent software. Configure Permissions: These permissions authorize the instance to make API calls to Oracle Cloud Infrastructure services, allowing the Block Volume Management plugin to report the iSCSI setup results for multipath-enabled iSCSI attachments.
To configure permissions:
-
Create Dynamic Group: Create a dynamic group with the matching rules in the following code sample, to include all instances in the specified compartments:
ANY {instance.compartment.id = 'ocid1.tenancy.oc1..<tenancy_ID>', instance.compartment.id = 'ocid1.compartment.oc1..<compartment_OCID>'} -
Configure Policy for Dynamic Group: Configure a policy granting permissions to the dynamic group created in the previous step to enable the instance agent access to call the Block Volume service to retrieve the attachment configuration.:
Allow dynamic-group InstantAgent to use instances in tenancy Allow dynamic-group InstantAgent to use volume-attachments in tenancy
-
Enabling Block Volume Management on New Instances
To enable Block Volume Management on a new compute instance, use the following steps.
- Follow the steps in Creating an Instance, until the advanced options. Ensure that the instance has either a public IP address or a service gateway, as described in the Prerequisites.
- Click Show Advanced Options.
-
On the Oracle Cloud Agent tab, select the Block Volume Management check box.
-
Click Create.
- Install the Oracle Cloud Agent software, if it is not already installed.
-
Use the UpdateInstance operation. Include the following parameters:
#oci compute instance update --instance-id <New_Instance> --agent-config file:///agentUpdate.json agentUpdate.json { "is-agent-disabled": false, "plugins-config": [ {"name": "Block Volume Management", "desiredState": "ENABLED" } ] } - Ensure that the instance has either a public IP address or a service gateway, as described in the Prerequisites.
Enabling Block Volume Management on Existing Instances
To enable Block Volume Management on an existing compute instance, use the following steps.
Install the Oracle Cloud Agent software, if it is not already installed. The Oracle Cloud Agent should already be installed all current and most recent platform images. Run the following command to check if it's already installed:
systemctl status oracle-cloud-agentIf the result is not found, you need to install the softare, otherwise proceed to the next step.
- Enable the Block Volume Management plugin.
- Confirm that plugins are running on the instance.
- Ensure that the instance has either a public IP address or a service gateway, as described in Prerequisites.
- Install the Oracle Cloud Agent software, if it is not already installed.
-
Use the UpdateInstance operation. Include the following parameters:
#oci compute instance update --instance-id <New_Instance> --agent-config file:///agentUpdate.json agentUpdate.json { "is-agent-disabled": false, "plugins-config": [ {"name": "Block Volume Management", "desiredState": "ENABLED" } ] } - Ensure that the instance has either a public IP address or a service gateway, as described in Prerequisites.
Manually Enabling Block Volume Management on an Instance
You can manually enable Block Volume Management on a compute instance using the CLI.
This procedure is only required for custom images that have been updated to support the
Ultra High Performance level, but the Block Volume Management plugin has not been
enabled in the /etc/oracle-cloud-agent/agent.yml file.
Prior to performing this procedure, you need to complete the steps described in Enabling Block Volume Management on New Instances or Enabling Block Volume Management on Existing Instances.
- Install the Oracle Cloud Agent software on the instance, if it is not already installed.
- Log into the instance, see Connecting to an Instance.
-
Run the following
sedscript to enable Block Volume Management:sed -i.saved -e '/^ oci-blockautoconfig:/,/^ [a-z]*:/{s/\(.*disabled:.*\)true/\1false/}' /etc/oracle-cloud-agent/agent.ymlThis script updates the
disabledparameter for theoci-blockautoconfigconfiguration in/etc/oracle-cloud-agent/agent.ymlfromtruetofalse. - Run the following command to restart the Oracle Cloud Agent service:
systemctl restart oracle-cloud-agent.service
Troubleshooting the Block Volume Management Plugin
If the Block Volume Management plugin is not configured correctly for an instance, you may encounter an error when attaching a volume with an iSCSI attachement type. See the troubleshooting suggestions in this section for these issues.
If you have not configured permissions correctly for the Block Volume Management plugin, the volume will fail to attach to the instance.
Details
The volume will not show up as attached in the Console and you will see a
NotAuthorizedOrNotFound error message in the Block Volume Management plugin log.
The Block Volume Management plugin log is located in:
"/var/log/oracle-cloud-agent/plugins/oci-blockautoconfig/oci-blockautoconfig.logThe following is an sample error log entry for this issue:
2021/08/13 09:14:25.864932 compute_client_command.go:255: Updating volume attachment to the state LOGIN_SUCCEEDED ...
2021/08/13 09:14:26.155473 compute_client_command.go:260: Service error:NotAuthorizedOrNotFound.
volume attachment ocid1.volumeattachment.oc1.iad.<volume-attachment_ID> not found.
http status code: 404. Opc request id: <request_ID>Cause
The Block Volume Management plugin does not have sufficent permissions to send the iSCSI login status notification to the service.
Resolution
To configure permissions for the Block Volume Management plugin:
-
Create Dynamic Group: Create a dynamic group with the matching rules in the following code sample, to include all instances in the specified compartments:
ANY {instance.compartment.id = 'ocid1.tenancy.oc1..<tenancy_ID>', instance.compartment.id = 'ocid1.compartment.oc1..<compartment_OCID>' -
Configure Policy for Dynamic Group: Configure a policy granting permissions to the dynamic group created in the previous step to enable the instance agent access to call the Block Volume service to retrieve the attachment configuration.:
Allow dynamic-group InstantAgent to use instances in tenancy Allow dynamic-group InstantAgent to use volume-attachments in tenancy
The compute instance must have either a public IP address or a service gateway to be able to connect to Oracle services or the volume will fail to attach.
Details
The volume will not show up as attached in the Console and you will see a
user agent can not be blank error message in the Block Volume Management plugin log.
The Block Volume Management plugin log is located in:
"/var/log/oracle-cloud-agent/plugins/oci-blockautoconfig/oci-blockautoconfig.logThe following is an sample error log entry for this issue:
2021/10/15 22:16:07.881953 compute_client_command.go:255: Updating volume attachment to the state LOGIN_SUCCEEDED ...
2021/10/15 22:16:07.882185 compute_client_command.go:260: user agent can not be blank
2021/10/15 22:16:07.882204 iscsi_commands_helper.go:302: user agent can not be blank
2021/10/15 22:16:07.882212 iscsi_commands_helper.go:310: user agent can not be blankCause
The Block Volume Management plugin cannot send the iSCSI login status notification to the service due to the network configuration.
Resolution
If the instance does not have a public IP address, set up a service gateway on the virtual cloud network (VCN). The service gateway lets your instance privately access Oracle services without exposing the data to the public internet. Here are special notes for setting up the service gateway for the Block Volume Management plugin:
- When creating the service gateway, enable the service label called All <region> Services in Oracle Services Network.
- When setting up routing for the subnet that contains the instance, set up a route rule with Target Type set to Service Gateway, and the Destination Service set to All <region> Services in Oracle Services Network.
For detailed instructions, see Access to Oracle Services: Service Gateway.