Update Bucket Metadata

This API covers how to update bucket metadata

A PATCH issued to the container metadata followed by a JSON string overwrites the specified mutable container metadata field.

Base Command

PATCH <accesser>:8338/container/{bucket.name}

Request

Table 1. Common Request Parameters
Request Parameter	Style	Required	Type	Description
If-Unmodified-Since	Header	Optional	String	Perform modification on the specified mutable metadata parameter if the container is not modified since the specified time, which user get from the time_updated field in metadata response; otherwise reject the change with conflict error, HTTP code 409. This header field is required for allowed_ip and denied_ip to avoid one user accidentally overwriting the change from the other users during concurrent modification. The format is HTTP-date according to RFC7232, https://tools.ietf.org/html/rfc7232#section-3.4. For example, If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT.
acl	Body	Optional	Array	An array of pairs of grantee and permission. If there are multiple permissions for the same grantee, multiple entries are required. Refer to table below called "acl array of pairs (PATCH)"
hard_quota	Body	Optional	String	Container hard quota bytes in positive value. Quotas apply only to new operations after a quota is exceeded. For example: If bucket quota is 100 GB and usage is 99GB, yet new request 10 GB, then the PUT Object request would be allowed to the bucket, usage after request will be 109 GB. The user will not be able to write more objects until usage brought below 100 GB (user must delete objects). Format BigInteger. When this is not provide, there is no quota restriction on the bucket. To remove the quota, set the value to 0.
firewall	Body	Optional	Object	The firewall restriction, including allowed or denied IP addresses list. When the firewall object is not provided in the body of the PATCH request, no change to the firewall rule. If only allowed IP address or denied IP address is provided, only the corresponding field will be updated, the other field that is omitted in the PATCH request will not be changed. To remove the denied IP or allowed IP address of a bucket, an empty array value must be explicitly provided. For example: allowed_ip: [], denied_ip:[] or both. When both are deleted, then no IP restriction, whether the bucket can be accessed depends on the IP access control at the vault level. If no IP access control specified for the vault, the bucket could be accessed from public IP. Update any parameter will replace its content. If firewall section is specified, either allowed_ip or denied_ip must be provided; otherwise return MalformedFirewallError. Refer to table below called "Firewall (PATCH)"
notifications	Body	Optional	Object	Optional notifications configuration for the container. This object is valid in on-premises cloud Container Mode when the Operator has configured the container vault to specify the notification topic for the container using the Service API. If the notifications object is not present, then notifications is disabled for the container. If notifications is disabled for a container when there are outstanding notifications (due to ongoing requests or due to retries for prior requests), then such notifications shall not be published. The Operator should use the Manager UI/REST API to determine the topic configuration setting for a container vault. Refer to table below called "Notifications (PATCH)"

Table 2. ACL array of pairs (PATCH)
Parameter	Type	Description
grantee	String	The storage account id or service instance granted to the permission.
permission	String	The permission for the grantee such as "READ", "WRITE, "READ_ACP", "WRITE_ACP" and "FULL_CONTROL."

Table 3. Firewall (PATCH)
Parameter	Type	Description	Format
allowed_ip	String	Array of string of allowed continuous non-overlapping IP address ranges for the container. If a request from a client IP that is not in this IP address list, the client request would be rejected. When this parameter is not provided, the bucket is allowed to be accessed from IP address other than those in denied_ip list. If neither is provided, bucket is allowed to be accessed from any IP address	Array of IPv4 or IPv6 addresses in CIDR format
denied_ip	String	Array of string of denied continuous non-overlapping IP address ranges for the container. If a request from a client IP that is in this IP address list, the client request would be rejected. Denied IP addresses might be used together with allowed IP as the “excluded sub-range of IP address” from the allowed large IP address range. When this parameter is not provided, the bucket is allowed to be accessed from IP address defined in allowed_ip list.	Array of IPv4 or IPv6 addresses in CIDR format

Table 4. Notifications (request)
Parameter	Type	Description	Format
topic	String	The topic on which the container's notifications shall be published. Notification of object-change events are published on this topic of the Notification Service assigned to the container vault, if the Notification Service is enabled. If topic is changed for a container when there are outstanding notifications (due to ongoing requests or due to retries for prior requests), then such notifications shall be published to the updated topic. Only a single topic is supported for a container. Note: Required, Yes if the notifications object is present.	1-249 characters in length. Valid characters: Alphanumeric, hyphen, period, underscore.

Response

Table 5. Response parameter
Response Parameter	Style	Type	Description
Bucket Object	Body	Object	The container metadata information, see GET command Response

Table 6. HTTP response codes
HTTP Response Code	Description
200 OK	The bucket was properly updated
400 Bad Request	Request the bucket is invalid, invalid hard quota, malformed acl, firewall or JSON. Detail error message is be provided on specific error etc. Request contains too many request element, request timeout, duplicate request header/fields, invalid argument, the bucket is a vault, invalid hard_quota, malformed acl, firewall or JSON, UnresolvableGrantByEmailAddress, Metadata too large, operation aborted, precondition failed,invalid format for notifications object, notifications object present when container vault is not assigned to a Notification Service or is not set to configure the topic at the container, notifications object specified in cloud mode, Notifications Service is disabled, etc . Detail error message is be provided on specific error.
401 Unauthorized	The provided token is invalid or could not be verified.
403 Forbidden	Access Denied
404 Not Found	The specified bucket does not exist
409 Conflict	Conflict in the PATCH request such as If-Unmodified-Since is evaluated to be true against the given container metadata last time_updated field, conflict in the ranges in IP restriction, between allowed_ip and denied_ip, or a conflict bucket creation is in progress.

Examples

For existing examples, refer to container level configuration service API. This sections shows only new/modified examples.

Example: Enable notifications on a container

Request

PATCH
<accesser>:8338/container/my-bucket

{ 
    "notifications":{ 
        "topic":"my-bucket_topic" 
    }
}

Response

The response shows the addition of notifications to existing container configuration.

HTTP/1.1 200 OK 
Content-Length: 263 
Content-Type: application/JSON; charset=utf-8 
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a 
Date: Mon, 15 Apr 2019 08:23:42 GMT 
X-Timestamp: 1537818417.22774 
{ 
   "storage_location":"us-south", 
   "name":"my-bucket", 
   "service_instance":"0050b1acd467454cbd693b279d72c3d2", 
   "acl":{ 
      "user1":[ "write" ] 
    }, 
    "retention_policy":{ 
       "status":"DISABLED" 
    }, 
    "cors":{ 
         "max_age_seconds":"6000", 
         "method":"GET", 
         "origin":"*.ibm.com" 
    }, 
    "hard_quota":"107374182400", 
    "firewall":{ 
         "allowed_ip":[ "192.168.10.0/24", "192.168.25.200/32" ],
         "denied_ip":[ "192.169.10.100/30" ] 
     }, 
    "notifications":{ 
        "topic":"my-bucket_topic" 
    },
    "time_created":"2019-04-12T00:56:10Z", 
    "time_updated":"2019-04-15T08:23:42Z" 
}

Example: Update quota

Request

PATCH
<accesser>:8338/container/my-bucket

{ 
   "hard_quota": 107374182400 
}

Response

The response shows when the firewall content when it is defined..

HTTP/1.1 200 OK 
Content-Length: 263 
Content-Type: application/JSON; charset=utf-8 
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a 
Date: Mon, 15 Apr 2019 08:23:42 GMT 
X-Timestamp: 1537818417.22774 
{ 
   "storage_location":"us-south", 
   "name":"my-bucket", 
   "service_instance":"0050b1acd467454cbd693b279d72c3d2", 
   "acl": { 
        "user1": ["WRITE","READ"],
        "user2": ["FULL-CONTROL"]
    }, 
    "retention_policy": { 
       "status":"DISABLED" 
    }, 
    "cors": { 
         "max_age_seconds":"6000", 
         "method":"GET", 
         "origin":"*.ibm.com" 
    }, 
    "hard_quota":"107374182400", 
    "firewall": { 
         "allowed_ip":[ "192.168.10.0/24", "192.168.25.200/32" ],
         "denied_ip":[ "192.169.10.100/30" ] 
     }, 
     "notifications": { 
         "topic":"my-bucket_topic", 
      },
    "time_created":"2019-04-12T00:56:10Z", 
    "time_updated":"2019-04-15T08:23:42Z" 
 }

Example: Update IP access control

A PATCH issued to the container metadata followed by a JSON string will update a specific mutable container security metadata field.

Below is an example for a request to update IP whitelisting using If-Unmodified-Since to prevent the accidentally overwritten from other user's simultaneous change.

Note: There is a gap of 192.168.10.100 to 192.168.10.103

192.168.10.0 to 192.168.10.99
192.168.10.104 .. 192.168.10.255
192.168.25.200

Request

PATCH
<accessor>:8338/container/my-bucket

PATCH <accesser>:8338/container/my-bucket
If-Unmodified-Since: Mon, 15 Apr 2019 08:23:42 GMT 
  {  
   "firewall":{  
      "allowed_ip":[  
          "192.168.28.100/24",
          "192.168.25.200",
          "2001:db8::/128",
          "fe80::202:b3ff:fe1e:832"
      ]
   }
}

Response

If current metadata last "time_updated" time matches the input value of "If-Unmodified-Since" in the header, the corresponding firewall IP access control attributes will be changed; otherwise, it will be rejected with 409 error.

After change the metadata, a response for the entire metadata is returned, and its body includes both allowed IP and denied IP, since only the allowed_ip is overwritten. If there is an old allowed_ip value, it would be replaced with the new content.

allowed_ip:"192.168.10.0/24","192.168.25.200/32", "2001:db8::/128", "fe80::202:b3ff:fe1e:832"

denied_ip: "192.168.10.100/30" (no change).

HTTP/1.1 200 OK
Content-Length: 263
Content-Type:application/JSON; charset=utf-8
X-Trans-Id:tx8ea13a3a835544d8bebf1-0056eb522a
Date: Mon, 15 Apr 2019 08:23:42 GMT
X-Timestamp: 1537818417.22774
{  
   "storage_location":"us-south",
   "name":"my-bucket",
   "service_instance":"0050b1acd467454cbd693b279d72c3d2",
   "acl": { 
      "user1": ["WRITE","READ"],
      "user2": ["FULL-CONTROL"]
   },
   "retention_policy":{  
      "minimum_retention":"3650",
      "maximum_retention":"7300",
      "default_retention":"3650",
      "permanent_retention":false
   },
   "cors":{  
      "max_age_seconds":6000,
      "method":["GET"],
      "origin":"*.ibm.com",
      "allowed_header":["*"],   
      "expose_header":[  
         "x-amz-server-side-encryption"
      ]
   },
   "hard_quota":107374182400,
   "firewall":{  
      "allowed_ip":[  
         "192.168.10.0/24",
         "192.168.25.200/32",
         "2001:db8::/128",
         "fe80::202:b3ff:fe1e:832"
      ],
      "denied_ip":[  
         "192.169.10.100/30"
      ]
   },
   "time_created":"2019-04-12T00:56:10Z",
   "time_updated":"2019-04-15T08:23:42Z"
}

Example: Delete IP access control

Below is an example for a request to delete the IP whitelist, which will not impact existing IP blacklist (denied IP).

Assume that below are configured for the bucket firewall.

allowed IP: 192.168.28.100/24
denied IP: 192.168.10.100/30

Request

PATCH
<accessor>:8338/container/my-bucket

PATCH <accesser>:8338/container/my-bucket
If-Unmodified-Since:
Mon, 15 Apr 2019 08:23:42 GMT  
  {  
   "firewall":{  
      "allowed_ip":[]
   }
}

Response

A response for the entire metadata is returned, including denied IP, but not the allowed_IP since the allowed_ip is removed.

denied_ip: "192.168.10.100/30"

HTTP/1.1 200 OK
Content-Length:263
Content-Type:application/JSON; charset=utf-8
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a
Date: Mon, 15 Apr 2019 08:23:42 GMT
X-Timestamp:1537818417.22774
{  
  "storage_location":"us-south",
  "name":"my-bucket",
  "service_instance":"0050b1acd467454cbd693b279d72c3d2",
  "acl": { 
      "user1": ["WRITE","READ"],
      "user2": ["FULL-CONTROL"]
   },
   "retention_policy":{       
      "minimum_retention":"3650",
      "maximum_retention":"7300",
      "default_retention":"3650",
      "permanent_retention":false
   },
   "cors":{  
      "max_age_seconds":6000,
      "method":["GET"],
      "origin":"*.ibm.com",  
      "allowed_header":["*"],   
      "expose_header":[  
        "x-amz-server-side-encryption"
      ]
   },
   "hard_quota":107374182400,
   "firewall":{  
      "denied_ip":[  
         "192.169.10.100/30"
      ]
   }, 
"time_created":"2019-04-12T00:56:10Z", 
"time_updated":"2019-04-15T08:23:42Z
}

Example: Disable notifications on a container

Request

PATCH
<accessor>:8338/container/my-bucket

{ 
   "notifications":{ 
   }
}

Response

A response with the entire metadata is returned. The notifications object is not present since notifications is disabled.

HTTP/1.1 200 OK
Content-Length:263
Content-Type:application/JSON; charset=utf-8
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a
Date: Mon, 15 Apr 2019 08:23:42 GMT
X-Timestamp:1537818417.22774
{  
  "storage_location":"us-south",
  "name":"my-bucket",
  "service_instance":"0050b1acd467454cbd693b279d72c3d2",
   "acl": { 
      "user1": ["WRITE","READ"],
      "user2": ["FULL-CONTROL"]
   },
   "retention_policy":{       
      "minimum_retention":"3650",
      "maximum_retention":"7300",
      "default_retention":"3650",
      "permanent_retention":false
   },
   "cors":{  
      "max_age_seconds":6000,
      "method":["GET"],
      "origin":"*.ibm.com",  
      "allowed_header":["*"],   
      "expose_header":[  
        "x-amz-server-side-encryption"
      ]
   },
   "hard_quota":107374182400,
   "firewall":{  
      "denied_ip":[  
         "192.169.10.100/30"
      ]
   }, 
   "time_created":"2019-04-12T00:56:10Z", 
   "time_updated":"2019-04-15T08:23:42Z
}

Example: Enable notifications on a container

Request

PATCH
<accesser>:8338/container/my-bucket

{ 
    "notifications":{ 
        "topic":"my-bucket_topic" 
    }
}

Response

The response shows the addition of notifications to existing container configuration.

HTTP/1.1 200 OK 
Content-Length: 263 
Content-Type: application/JSON; charset=utf-8 
X-Trans-Id: tx8ea13a3a835544d8bebf1-0056eb522a 
Date: Mon, 15 Apr 2019 08:23:42 GMT 
X-Timestamp: 1537818417.22774 
{ 
   "storage_location":"us-south", 
   "name":"my-bucket", 
   "service_instance":"0050b1acd467454cbd693b279d72c3d2", 
   "acl": { 
       "user1": ["WRITE","READ"],
       "user2": ["FULL-CONTROL"]
    },
    "retention_policy":{ 
       "status":"DISABLED" 
    }, 
    "cors":{ 
         "max_age_seconds":"6000", 
         "method":"GET", 
         "origin":"*.ibm.com" 
    }, 
    "hard_quota":"107374182400", 
    "firewall":{ 
         "allowed_ip":[ "192.168.10.0/24", "192.168.25.200/32" ],
         "denied_ip":[ "192.169.10.100/30" ] 
     }, 
    "notifications":{ 
        "topic":"my-bucket_topic" 
    },
    "time_created":"2019-04-12T00:56:10Z", 
    "time_updated":"2019-04-15T08:23:42Z" 
}

Example: Update bucket ACL

A bucket PATCH request with input of full list of acl object will return the full acl objects in response, and the entire acl list is overwritten.

Request

PATCH
<accesser>:8338/container/my-bucket

{ 
  "acl": [ 
    { "grantee": "user1",
      "permission: "WRITE"
    },
    {
      "grantee": "user2",
      "permission": "FULL_CONTROL"
    }
  ] 
}

Response

See GET command, all parameters retrieved.