Managing namespaces
IBM Cloud® Functions is deprecated. Existing Functions entities such as actions, triggers, or sequences will continue to run, but as of 28 December 2023, you can’t create new Functions entities. Existing Functions entities are supported until October 2024. Any Functions entities that still exist on that date will be deleted. For more information, see Deprecation overview.
With IBM Cloud® Functions, you can create Identity and Access (IAM) managed namespaces to group entities, such as actions or triggers, together. Then, you can create IAM access policies for the namespace.
What is a namespace?
Namespaces contain Cloud Functions entities, such as actions and triggers, and belong to a resource group. You can let users access your entities by granting them access to the namespace.
The fully qualified name of an entity is /<namespace_ID>/<package_name>/<entity_name>
.
What happens when I create a namespace?
Namespaces that are created within Cloud Functions are identified as an IAM service instance. When you create a namespace, you can specify the resource group in which to add the service instance.
When you create a namespace, the following components are created:
Component | Description |
---|---|
Service ID | You can use the service ID as a functional ID when you make outbound calls. All the actions that are created in this namespace can use this service ID for access to other resources. The functional user gets the Reader role by default. Reader access means it can read namespace entities and invoke actions. The Reader role is used by triggers to invoke actions. To control inbound traffic, you might want to grant access to other users such as assigning Reader role to invoke actions. |
API key | An API Key for the service ID that can be used to generate IAM tokens. You can use the tokens to authenticate the namespace with other IBM Cloud services. The API key is provided to actions as the environment variable __OW_IAM_NAMESPACE_API_KEY . |
You can view a list of your service IDs by running the following command.
ibmcloud iam service-ids
You can view the API keys that are associated with a service ID by running the following command.
ibmcloud iam service-api-keys <ServiceID-12345678-1234-abcd-1234-123456789abc>
Do not delete service IDs or API keys.
Are there any limitations for namespaces?
The mobile SDK is not supported for IAM-managed namespaces.
The names of all entities, including actions, triggers, rules, packages, and namespaces, are a sequence of characters that follow the following format:
- The first character must be an alphanumeric character, or an underscore.
- The subsequent characters can be alphanumeric, spaces, or any of the following values:
_
,@
,.
,-
. - The last character can't be a space.
What do I do if I have a Cloud Foundry-based namespace?
Your Cloud Foundry-based namespaces still work. However, to take advantage of new features, you must create an IAM-enabled namespace.
You can target a Cloud Foundry-based namespace or IAM-enabled namespace by running ibmcloud fn property set --namespace <namespace_name_or_ID>
or ibmlcoud fn namespace target <namespace_name_or_ID>
.
As a result of the Cloud Foundry service deprecation, Cloud Foundry-based namespaces in Cloud Functions are deprecated and will stop working on Oct 31st, 2023. If you are still using Cloud-Foundry-based namespaces, migrate your namespace to an IAM namespace to ensure that your Cloud Function workloads continue to run.
How do I see a list of my Cloud Functions namespaces?
You can see a list of your Cloud Functions namespaces by running the namespace list
command. The command output includes all the namespaces
in the currently selected region and also lists whether the namespace is a Cloud Foundry-based or an IAM-based namespace. Note that the namespace list
command is scoped to the targeted region and resource group that you set.
To view your current region and resource group, run ibmcloud target
. To set your region and resource group to a different choice, run ibmcloud target -r REGION -g RESOURCE_GROUP
, where REGION
and RESOURCE_GROUP
are the new targets.
ibmcloud fn namespace list
The following example shows sample output from the ibmcloud fn namespace list
command.
name type id description
dev CF-based dev
cfsdocs_prod CF-based prod
playground IAM-based <id_string> IAM playground.
You can see a list of your IAM-based namespaces in the IBM Cloud Console Resource list or by using the resource service-instances
CLI command. This command lists Cloud Functions namespaces of all regions.
ibmcloud resource service-instances --service-name functions
The following example shows sample output from the ibmcloud resource service-instances --service-name functions
command.
Name Location State Type
playground us-south active service_instance
How do I see the Cloud Functions entities in my namespace?
You can see a list of your Cloud Functions entities by running the namespace get
command. Replace <namespace_name>
or <namespace_id>
with the name or ID of your namespace.
ibmcloud fn namespace get <namespace_name> or <namespace_id>
Creating an IAM-based namespace
You can create an IAM-managed namespace as part of a resource group and manage access policies for your resources by targeting the resource group when a namespace is created. If you have other users that require access to your namespace, or if you want to access other resources from your namespace's actions, be sure that you set IAM policies after your namespace is created.
If you are creating a namespace in a resource group of an account that is not your own, you must have the Administrator Platform access role for Cloud Functions. Account owners have the Administrator role by default. For more information, see Platform management roles.
If you are an Administrator and want to allow other users to create namespaces, see How do I set IAM policies so that others can create namespaces in my account?.
Creating an IAM-based namespace from the console
Create your IAM-based namespace by using the console.
- From the Cloud Functions console namespace menu, select Create namespace.
- Enter a display name for the namespace and a short description, such as the actions or packages that you plan to create in this namespace.
- Choose the resource group where you want to create the namespace and a location to deploy the namespace resource.
- Click Create.
- To view the service instance for the namespace resource, go to your IBM Cloud dashboard and find your namespace name in Functions namespaces.
You can update the name or description of the namespace from the Namespace settings page in the Cloud Functions console.
Creating an IAM-based namespace with the CLI
You can create an IAM-managed namespace with the CLI.
-
Target the resource group where you want to create the namespace. If you haven't created a resource group yet, you can target the
default
group.ibmcloud target -g default
-
Create an IAM-enabled namespace. Optional: Include a description for your namespace by using the
-n
or--description
flag. If your description is longer than one word, it must be in quotations.ibmcloud fn namespace create <namespace_name> [--description <"description of your namespace">]
|
<namespace_name>
| The display name for the IAM-based namespace. | |-n <description>
| Optional: Add a description to the namespace, such as which kind of actions or packages you plan to create. If your description is longer than one word, it must be in quotations. | |--description <description>
| Optional: Add a description to the namespace, such as which kind of actions or packages you plan to create. If your description is longer than one word, it must be in quotations. |The following example shows sample output from the
namespace create
command.ok: created namespace myNamespace
-
Verify that your new namespace is created.
ibmcloud fn namespace get <namespace_name_or_id> --properties
The following example shows sample output from the
namespace get
command.Details of namespace: myNamespace Description: short description Resource Plan Id: functions-base-plan Location: jp-tok ID: 05bae599-ead6-4ccb-9ca3-94ce8c8b3e43
You can also list all namespaces, including IAM-based and Cloud Foundry-based namespaces:
ibmcloud fn namespace list
-
Before you can create entities in the namespace, you must set your CLI context to the namespace by targeting it.
ibmcloud fn property set --namespace <namespace_name_or_id>
After you set a property, such as the --namespace
property, it is retained until you manually unset it. If you want to switch between IAM namespaces or between Cloud Foundry and IAM namespaces, you must unset the namespace property
and then reset it. For more information, see ibmcloud fn property set
.
Creating a namespace with the API
Create your IAM-managed namespace with the API.
-
Create an IAM-enabled namespace.
curl --request POST \ --url 'https://jp-tok.functions.cloud.ibm.com/api/v1/namespaces' \ --header 'accept: application/json' \ --header 'authorization: <IAM_token>' \ --data '{"description":"string","name":"string","resource_group_id":"string","resource_plan_id":"string"}'
|
<IAM_token>
| Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, runibmcloud iam oauth-tokens
. | |-n <name>
| The name of the namespace. | |-n <resource_group_id>
| The ID of the resource group that you want to create the namespace in. To see resource group IDs, runibmcloud resource groups
. | |-n <resource_plan_id>
| The ID of the resource plan, such as functions-base-plan | |-n <description>
| Optional: Add a description to the namespace, such as which kind of actions or packages it will contain. |The following example shows sample output from the previous command.
{ "description": "My new namespace for packages X, Y, and Z.", "id": "12345678-1234-abcd-1234-123456789abc", "location": "jp-tok", "crn": "crn:v1:functions:jp-tok:a/1a22bb3c44dd1a22bb3c44dd1a22:12345678-1234-abcd-1234-123456789abc::", "name": "mynamespace", "resource_group_id": "1a22bb3c44dd1a22bb3c44dd1a22", "resource_plan_id": "functions-base-plan" }
-
Verify that your new namespace is created.
curl --request GET \ --url 'https://us-south.functions.cloud.ibm.com/api/servicebroker/api/v1/namespaces/{id} \ --header 'accept: application/json' \ --header 'authorization: <IAM_token>'
You can also list all namespaces, including IAM-based and Cloud Foundry-based namespaces:
curl --request GET \ --url 'https://jp-tok.functions.cloud.ibm.com/api/v1/namespaces?limit=0&offset=0' \ --header 'accept: application/json' \ --header 'authorization: <IAM_token>'
The following example shows sample output from the previous command.
{ "limit": 10, "offset": 0, "total_Count": 2, "namespaces": [ { "id": "12345678-1234-abcd-1234-123456789abc", "location": "jp-tok" }, { "id": "BobsOrg_dev", "classic_type": 1, "location": "jp-tok" } ] }
For more information about working with HTTP REST, check out the Cloud Functions API Docs.
Optional workflow: Creating namespaces for staging and production deployments
You can create IAM-enabled namespaces to handle your pre-production (staging) and production Cloud Functions deployments by creating namespaces for each. Run ibmcloud fn namespace create
to create more namespaces under your account such as "staging" and "production":
-
Create a staging namespace.
ibmcloud fn namespace create staging
-
Create a production namespace.
ibmcloud fn namespace create production
Cloud Functions has restrictions on namespace names. For more information, see the System details and Limits documentation.
Targeting namespaces
Before you can work in Cloud Functions, you must target a namespace. You can target IAM namespaces or Cloud Foundry namespaces.
To target a namespace, use the ibmcloud fn namespace target
command or the ibmcloud fn property set --namespace <namespace_name_or_ID>
command.
For example, to target an IAM namespace called playground
,
ibmcloud fn namespace target playground
Accessing other resources from a namespace
Actions typically call other IBM Cloud resources and services that require appropriate authentication. If these services are IAM-enabled and accept IAM tokens, you can leverage the namespace functional ID for outbound communication.
As described in Managing IAM access, for each namespace, a service ID is created that represents the namespace. You can grant access to other services and resources for this service ID by assigning the appropriate roles by using IAM policy management. For more information about creating service IDs to access other IAM-enabled services, see Creating and working with service IDs.
At runtime, Cloud Functions passes an API key of the namespace service ID to the action code as the environment variable __OW_IAM_NAMESPACE_API_KEY
. The action code can use this API key to generate an IAM token. Most of the supported
Cloud Functions SDKs such as Cloudant, Watson, and IBM Cloud Object Storage authenticate with the IAM API key itself. For other IAM-managed services or resources that use a REST API, you can authenticate with the token that is derived from
the IAM API key. For more information, see Create an IAM access token for a user or service ID.
Next steps for namespaces
Not sure how API keys and tokens fit together? Learn more in the IAM Docs.
Now that you created a namespace, you can create IAM access policies to help protect it. To get started, check out Managing access.
For more information about how to manage IAM-based namespaces, see the Cloud Functions REST API reference.