Managing namespaces

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:

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 from the console

Create your IAM-based namespace by using the console.

1. From the Cloud Functions console namespace menu, select Create namespace.
2. 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.
3. Choose the resource group where you want to create the namespace and a location to deploy the namespace resource.
4. Click Create.
5. 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.

1. 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
   

2. 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
   

3. 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
   

4. 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.

1. 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, run ibmcloud 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, run ibmcloud 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"
   }
   

2. 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.

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.