Create a plugin

This page describes how to create Service Extensions plugins that you can use to implement extensibility with Google Cloud services.

This feature is in Preview for Media CDN.

For a product overview, see Service Extensions overview.

Before you begin

  1. Prepare and upload the files required to create a plugin.

  2. Get the required Identity and Access Management (IAM) roles and permissions.

  3. Enable the Network Services API, if it's not already enabled.

    gcloud services enable networkservices.googleapis.com

  4. If you intend to enable logging for the plugin, enable the Network Actions API.

    gcloud services enable networkactions.googleapis.com

Create a plugin

Creating a plugin entails specifying a container image that contains the plugin code and specifying labels and logging options for the plugin.

Console

To create a plugin, follow these steps:

  1. In the Google Cloud console, go to the Service Extensions page.

    Go to Service Extensions

  2. Click the Plugins tab.

  3. Click Create plugin.

  4. In the Basics section, do the following:

    1. Enter a unique plugin name.

      The name must start with a lowercase letter followed by up to 62 lowercase letters, numbers, or hyphens and must not end with a hyphen.

    2. Optional: Enter a brief description about the plugin by using up to 1024 characters.

  5. In the Container image section, do the following:

    1. For Plugin version name, specify a name for the plugin version.

      The name must start with a lowercase letter followed by up to 62 lowercase letters, numbers, or hyphens and must not end with a hyphen.

    2. Optional: For Plugin version description, enter a brief description about the plugin version by using up to 1024 characters.

    3. For Container image URL, click Select, and then select the container image with the Wasm module from the Artifact Registry pane.

      The Artifact Registry pane displays the folders in the repository that's connected to the current project.

      To select a container image from another project, ensure that Service Extensions has access to it, and then click Change, next to the project name.

    4. Locate the container image, and then click Select.

  6. Optional: In the Plugin configuration section, to associate a configuration file with the plugin, select the Add plugin configuration checkbox, and then select either of the following options:

    • Upload plugin configuration file: If your file size is less than 900 KiB, click Browse to locate the file in your local drive.

    • Select plugin configuration image from Artifact Registry: If your file size is more than 900 KiB, click Select, and then select the image from the Artifact Registry pane.

  7. Optional: In the Labels section, click Add label. Then, in the row that appears, do the following:

    1. For Key, enter a key name.
    2. For Value, enter a value for the key.

    To add more key-value pairs, with the maximum limit being 64, click Add label.

    For more information about labels, see Create and update labels.

  8. Optional: In the Logging section, select Enable logging and do the following:

    • For Sample rate, specify a value between 0 and 1. The value 0 indicates that log messages are not stored. The default value 1 indicates that all log messages are stored. A floating point value between 0.0 and 1.0 indicates that a percentage of log messages is stored.

    • For Minimum log level, select the minimum severity level of plugin log messages to be exported to Cloud Logging. The default value is Info and higher.

  9. Click Create.

gcloud

  1. Create a plugin by running the gcloud service-extensions wasm-plugins create command:

    gcloud service-extensions wasm-plugins create WASM_PLUGIN \
    --description=PLUGIN_DESCRIPTION \
    --labels=[LABELS,...] \
    --log-config=[LOG_CONFIG,...] \
    --image=IMAGE \
    --main-version=MAIN_VERSION \
    --plugin-config=PLUGIN_CONFIG | --plugin-config-file=PLUGIN_CONFIG_FILE | --plugin-config-uri=PLUGIN_CONFIG_URI

    Replace the following:

    • WASM_PLUGIN: the ID or the fully qualified name of the plugin
    • PLUGIN_DESCRIPTION: a description of the plugin
    • LABELS: labels in the form of key-value pairs separated by commas

    • LOG_CONFIG: logging options for the plugin. When the enable option is set to false, logs are not captured for the plugin. To enable logging, set the enable option to true. Then, specify the following details:

      • sample-rate: the sampling rate of activity logs as a value between 0 and 1. The value 0 indicates that log messages are not stored. The default value 1 indicates that all log messages are stored. A floating point value between 0.0 and 1.0 indicates that a percentage of log messages is stored.

      • min-log-level: the minimum severity level of plugin log messages to be exported to Cloud Logging. The default value is INFO.

    • IMAGE: the URI of the container image with the Wasm module stored in the Artifact Registry repository. Before you specify a container image from another project, ensure that Service Extensions has access to it.

    • MAIN_VERSION: the ID of the plugin version to create and set as the main (active) version

    • PLUGIN_CONFIG, PLUGIN_CONFIG_FILE, or PLUGIN_CONFIG_URI: the optional configuration data, which can be specified as text, a local file, or a container image in Artifact Registry, respectively

    For example:

    gcloud service-extensions wasm-plugins create my-plugin \
    --description="This is my plugin." \
    --log-config=enable=true,sample-rate=0.5,min-log-level=INFO \
    --labels=key1=value1,key2=value2 \
    --image=...-docker.pkg.dev/my-project/repository/container:tag \
    --main-version=v1 \
    --plugin-config=config.txt

    To deploy a new version, use the gcloud service-extensions wasm-plugins update command command. Specify a new image (with the same tag or a new tag) and version name:

    gcloud service-extensions wasm-plugins update my-plugin \
    --image=...-docker.pkg.dev/my-project/repository/container:tag \
    --main-version=v2

To run these plugins, you can configure Cloud Load Balancing extensions and Media CDN extensions.

Access container images in another project

Before you can select container images from another project, the Service Extensions service agent must have access to the project repository and artifactregistry.repositories.downloadArtifacts permission on the project.

The Service Extensions service agent is named as follows:

service-PROJECT_NUMBER@gcp-sa-networkactions.iam.gserviceaccount.com

Replace PROJECT_NUMBER with your project number.

What's next