Restricting network access

By default, Event Streams instances are configured to use the IBM Cloud® public network, so they are accessible over the public internet.

If required, you can use network type or context-based restrictions to restrict the network connectivity as follows:

Network type: IBM Cloud offers both private and public networking. If your workload is running entirely within the IBM Cloud, and public access to the service is not required, Event Streams instances can instead be configured to be accessible only over the IBM Cloud private network. This offers increased isolation and does not incur the egress bandwidth charges associated with public traffic. Instances can also be configured to be accessible over both the IBM Cloud public and private networks, where your workload can use the most appropriate interface for its location. You can find further information about private networking at Virtual routing and forwarding on IBM Cloud.
Context-based restrictions (CBR): You can define access rules that limit the network locations that connections are accepted from. For example, network type, IP ranges, VPC, or other services. For more information, see What are context-based restrictions.; Auditing events for context-based restrictions are published under context-based restrictions IBM Cloud Activity Tracker events Context-based restrictions rules events. Activity Tracker events related to CBR enforcement are unavailable on private endpoints.

Configuring the network type

You can configure Enterprise service instances to be available on the IBM Cloud private, public, or private and public networks. The following information describes how to select and update the required networking type. Public networking is selected by default.

Prerequisites

Ensure that you complete the following tasks:

Create your service instance by using the Enterprise plan in one of the supported multi-zone locations. For more information, see Choosing your plan.
Enable Virtual Route Forwarding (VRF) for your IBM Cloud account.
Enable service endpoints connectivity by running the following command:
```
ibmcloud account update --service-endpoint-enable true
```
To check whether prerequisites are completed, run the following command, and then check whether the following two properties are true:
```
ibmcloud account show

VRF Enabled:                        true
Service Endpoint Enabled:           true
```

Selecting a network configuration during provisioning

You have a number of options for selecting the network configuration of your Enterprise cluster.

Use the IBM Cloud public network. Endpoints are accessible on the public internet. This is the default.
Use the IBM Cloud private network. Endpoints are not visible on the public internet.
Use the IBM Cloud public and private network. Endpoints are visible on both the public internet and internally within the IBM Cloud.

You can make this selection at provision time through the Event Streams catalog provisioning page. Use the Service Endpoints menu drop- down to select either Public (default), Private or Public and Private.

Alternatively, if you want to use the CLI to provision an Event Streams service, use the following commands:

To enable public endpoints (the default):

ibmcloud resource service-instance-create <instance-name> messagehub ibm.message.hub.enterprise.3nodes.2tb <region> --service-endpoints public

To enable private only endpoints:

ibmcloud resource service-instance-create <instance-name> messagehub ibm.message.hub.enterprise.3nodes.2tb <region> --service-endpoints private

To enable both private and public endpoints:

ibmcloud resource service-instance-create <instance-name> messagehub ibm.message.hub.enterprise.3nodes.2tb <region> --service-endpoints public-and-private

Updating the network configuration

You can also switch the endpoints that your Enterprise cluster uses after provisioning. To do this, use the following CLI commands:

To migrate directly from public or private to public-and-private endpoints:

ibmcloud resource service-instance-update <instance-name> --service-endpoints public-and-private

To migrate from public-and-private to public endpoints:

ibmcloud resource service-instance-update <instance-name> --service-endpoints public

To migrate from public-and-private to private endpoints:

ibmcloud resource service-instance-update <instance-name> --service-endpoints private

Switching directly from public to private endpoints or from private to public endpoints is not supported. The switch disables all public endpoints and your applications loses access to the cluster. To avoid this, first enable both public and private endpoints, then reconfigure applications to use private endpoints, and finally switch to private only endpoints.

For example, to migrate from public to private endpoints:

First, enable both public and private endpoints:

ibmcloud resource service-instance-update <instance-name> --service-endpoints public-and-private

Next, create a new credential that contains private endpoints and a new API key, as follows:

ibmcloud resource service-key-create <private-key-name> <role> --instance-name <instance-name> --service-endpoint private

Then, update any applications that use the instance with the new service key and endpoint details.

Finally, after applications are migrated to the private endpoints, run the following command to turn off the public endpoints:

ibmcloud resource service-instance-update <instance-name> --service-endpoints private

Specifying an IP allowlist (deprecated)

This feature is now deprecated, instead use context-based restrictions Configuring CBR.

When you provision an instance of the Enterprise plan, select private endpoints and want to further restrict access to only known VSIs with specific VPCs, you can add an IP allowlist by using the CLI and appending as follows:

ibmcloud resource service-instance-create <instance-name> <plan-name> <region> --service-endpoints private -p '{"private_ip_allowlist":["CIDR1","CIDR2"]}' "

where CIDR1, CIDR2 are IP addresses of the form a.b.c.d/e. The array of CIDRs can have any number of elements.

Alternatively, to update the IP allowlist for an existing service instance, complete the following steps:

Obtain the original IP allowlist applied on the instance:

$ibmcloud es init -i <instance-name>
API Endpoint:		https://mh-cktmqpdbvkfczhmn.us-south.containers.appdomain.cloud
Service endpoints:	public-and-private
Private IP allowlist:	"10.243.0.8/32","10.243.128.8/32","10.243.64.4/32"
Storage size:		4096 GB
Throughput:		300 MB/s
OK

Add CIDRs into or delete CIDRs from the Private IP allowlist.

Run the following command to update the service instance with a new list:

ibmcloud resource service-instance-update <instance-name> --service-endpoints private -p '{"private_ip_allowlist":["CIDR1","CIDR2"]}'

where CIDR1, CIDR2 are IP addresses of the form a.b.c.d/e

If the private endpoint is enabled by using the CLI, the next time you update the private IP allowlist, you can omit --service-endpoints private.

Switching IP allowlists disable any allowed IP address not in the new list. Applications accessing the cluster from those addresses lose access to the cluster.

Retrieving endpoint information

The endpoint information for your service instance is specific to the network type. Service instances with both public and private networking selected have an endpoint for each.

You can retrieve the endpoint information for the required network type by using the --service-endpoint option of the service-key-create CLI command as follows:

ibmcloud resource service-key-create <private-key-name> <role> --instance-name <instance-name> --service-endpoint private

Accessing the IBM Event Streams console

The console continues to be accessible if public networking is available for the instance, including both public and public-and-private.

The console will not be accessiable if private only network is selected and context-based restriction is setup due to technical limitation. CLI is recommended to perform any administrative operations. eg. ibmcloud es topic-create [--name] TOPIC_NAME [--partitions PARTITIONS] [--config KEY=VALUE[;KEY=VALUE]* ]*

Configuring context-based restrictions

You can define rules that limit the network locations that connections are accepted from. For example, by network type, IP ranges, VPC, or from other services. For more information, see What are context-based restrictions?

Context-based restrictions can be defined for both Standard and Enterprise plan Event Streams instances. When context-based restrictions rules are defined, the following rules apply:

Admin REST API, REST Producer API, Schema Registry API, and Kafka client calls are under the scope of context-based restrictions rules that are created against an Event Streams instance.
The Administration functions for the service instance itself (for example the IBM Cloud CLI service-instance-create, service-instance-delete or service-instance-update commands, or equivalent) are not under the scope of the context-based restrictions rules that are created against an Event Streams instance.

Managing context-based restrictions settings

Creating context-based restrictions rules is a two-step process:

Create a network zone with list of allowed IP addresses, allowed VPCs, or reference a service. For more information, see Creating network zones.
Create rules that specify one or more network zones against the Event Streams resource. For more information about rule creation, see Creating rules.

Next, note the following considerations:

You must be the account owner or have an access policy with the administrator role on all account management services to restrict access.
After creating or updating a zone or a rule, it can take a few minutes (up to 10 minutes) for the change to take effect.
After context-based restrictions are applied, they are only enforced for clients that authenticate after the rule has been created. Existing clients should reauthenticate for restriction rules to be enforced.

Supporting connections between services (service-to-service) with context-based restrictions

If an Event Streams service instance is configured to use customer-managed encryption, the service must also be granted the ability to connect to the selected IBM Key Management Services.

The administrator of the account can set this up as follows:

Add a service reference for the Event Streams service to the required network zone.
Ensure that access from this zone is permitted by way of the context-based restrictions rules applicable to other Cloud services.

For more information about service reference creation, see Service references.

Coexistence of context-based restrictions rules and private IP allowlists

Context-based restrictions rules now supersede the use of private IP allowlists as the recommended approach for implementing allowlists against an Event Streams instance. The use of private IP allowlists continues to be supported but is now deprecated.

If both context-based restrictions rules and IP allowlists are defined against the same Event Streams instance, the IP allowlist is ignored because the context-based restrictions rules override any previous private IP allowlist.

Migrating from private IP allowlists to context-based restrictions

The customer is responsible for migration. You can create IP allowlist definitions again as context-based restrictions network zones and apply them to the service instance by creating a context-based restrictions rule. You can then delete the previous private IP allowlist.