IBM Cloud Docs
Managing namespaces

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:

Table 1. Components of a namespace
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.

  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.

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.