Prepare the plugin code

The custom code that you create for Service Extensions plugins must be packaged and uploaded to Artifact Registry before other services can access it. This page describes how to create plugin code, package the code, and upload it to an Artifact Registry repository.

This feature is in Preview for Media CDN.

For information about Service Extensions, see Service Extensions overview.

Before you start, review the best practices for writing plugin code.

For more examples, see Code samples for plugins.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Network Services, Network Actions, Artifact Registry, Cloud Build, Cloud Logging, and Cloud Monitoring APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Network Services, Network Actions, Artifact Registry, Cloud Build, Cloud Logging, and Cloud Monitoring APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  11. Install the Google Cloud CLI.

  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  13. To initialize the gcloud CLI, run the following command: 

    gcloud init

Set up the toolchain

C++

The Proxy-Wasm C++ SDK let developers use C++ to implement WebAssembly (Wasm) plugins for Service Extensions. The SDK uses the C++ WebAssembly toolchain Emscripten, as well as other libraries, such as protobuf and, optionally, Abseil.

Because building plugins written in C++ depends on specific versions of these tools and libraries, we recommend using the Docker image provided by the Proxy-Wasm C++ SDK. The instructions for C++ on this page use the Docker method. To build C++ plugins without using Docker, see the Proxy-Wasm C++ SDK documentation.

  1. Install Docker if it's not already installed. Docker is included in Cloud Shell, the Google Cloud interactive shell environment.

  2. Download a copy of the Proxy-Wasm C++ SDK. The simplest way to do this is to clone the Git repository:

    git clone https://github.com/proxy-wasm/proxy-wasm-cpp-sdk.git

  3. Build the Proxy-Wasm C++ SDK Docker image from the Dockerfile provided by the SDK:

    cd proxy-wasm-cpp-sdk
docker build -t wasmsdk:v3 -f Dockerfile-sdk .

    When the command completes building SDK libraries and dependencies, the resulting Docker image is associated with the specified tag, which is wasmsdk:v3 in this example.

Go

The Proxy-Wasm Go SDK provides a full-feature Go SDK. Go provides good performance and rich support for third-party libraries written in pure Go.

Install the Go toolchain v1.24.0.

Rust

The customization capability of Service Extensions is provided through the use of WebAssembly and Proxy-Wasm. WebAssembly supports a number of programming languages. Google recommends Rust because it provides excellent WebAssembly support and Proxy-Wasm provides a full-featured Rust SDK. Rust also provides good performance and strong type safety.

  1. Install the Rust toolchain.

    At the end of the installation process, follow any instructions printed to the console to finish the configuration process.

  2. Add Wasm support to the Rust toolchain:

    rustup target add wasm32-wasip1

Create the plugin package

C++

  1. Create a new directory, separate from proxy-wasm-cpp-sdk:

    mkdir myproject

  2. In the directory, create a Makefile with the following contents:

    # Express any dependencies
PROTOBUF=     # full / lite / none
WASM_DEPS=    # absl_base re2 ...

# Include the SDK Makefile
PROXY_WASM_CPP_SDK=/sdk
include ${PROXY_WASM_CPP_SDK}/Makefile

  3. Add a C++ source file for the plugin in the same directory. The names of C++ source files must match the Wasm files that the Makefile targets, with the .wasm suffix replaced by .cc. In this example, the source file must be named myproject.cc.

  4. Add your plugin code to the source file.

    The following sample source code is a plugin that rewrites the request host, and emits a response header:

    #include "proxy_wasm_intrinsics.h"

class MyHttpContext : public Context {
 public:
  explicit MyHttpContext(uint32_t id, RootContext* root) : Context(id, root) {}

  FilterHeadersStatus onRequestHeaders(uint32_t headers,
                                       bool end_of_stream) override {