Instance
User-friendly container for Google Cloud Bigtable Instance.
class google.cloud.bigtable.instance.Instance(instance_id, client, display_name=None, instance_type=None, labels=None, _state=None)
Bases: object
Representation of a Google Cloud Bigtable Instance.
We can use an Instance
to:
reload()
itselfcreate()
itselfupdate()
itselfdelete()
itself
NOTE: For now, we leave out the default_storage_type
(an enum)
which if not sent will end up as data_v2_pb2.STORAGE_SSD
.
Parameters
instance_id (str) – The ID of the instance.
client (
Client
) – The client that owns the instance. Provides authorization and a project ID.display_name (str) – (Optional) The display name for the instance in the Cloud Console UI. (Must be between 4 and 30 characters.) If this value is not set in the constructor, will fall back to the instance ID.
instance_type (int) – (Optional) The type of the instance. Possible values are represented by the following constants:
google.cloud.bigtable.enums.Instance.Type.PRODUCTION
.google.cloud.bigtable.enums.Instance.Type.DEVELOPMENT
, Defaults togoogle.cloud.bigtable.enums.Instance.Type.UNSPECIFIED
.labels (dict) – (Optional) Labels are a flexible and lightweight mechanism for organizing cloud resources into groups that reflect a customer’s organizational needs and deployment strategies. They can be used to filter resources and aggregate metrics. Label keys must be between 1 and 63 characters long. Maximum 64 labels can be associated with a given resource. Label values must be between 0 and 63 characters long. Keys and values must both be under 128 bytes.
_state (int) – (OutputOnly) The current state of the instance. Possible values are represented by the following constants:
google.cloud.bigtable.enums.Instance.State.STATE_NOT_KNOWN
.google.cloud.bigtable.enums.Instance.State.READY
.google.cloud.bigtable.enums.Instance.State.CREATING
.
app_profile(app_profile_id, routing_policy_type=None, description=None, cluster_id=None, allow_transactional_writes=None)
Factory to create AppProfile associated with this instance.
For example:
from google.cloud.bigtable import Client
from google.cloud.bigtable import enums
routing_policy_type = enums.RoutingPolicyType.ANY
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
description = "routing policy-multy"
app_profile = instance.app_profile(
app_profile_id=APP_PROFILE_ID,
routing_policy_type=routing_policy_type,
description=description,
cluster_id=CLUSTER_ID,
)
app_profile = app_profile.create(ignore_warnings=True)
Parameters
app_profile_id (str) – The ID of the AppProfile. Must be of the form
[_a-zA-Z0-9][-_.a-zA-Z0-9]\*
.Type
routing_policy_type: int
Param
routing_policy_type: The type of the routing policy. Possible values are represented by the following constants:
google.cloud.bigtable.enums.RoutingPolicyType.ANY
google.cloud.bigtable.enums.RoutingPolicyType.SINGLE
Type
description: str
Param
description: (Optional) Long form description of the use case for this AppProfile.
Type
cluster_id: str
Param
cluster_id: (Optional) Unique cluster_id which is only required when routing_policy_type is ROUTING_POLICY_TYPE_SINGLE.
Type
allow_transactional_writes: bool
Param
allow_transactional_writes: (Optional) If true, allow transactional writes for ROUTING_POLICY_TYPE_SINGLE.
Return type
AppProfile>
Returns
AppProfile for this instance.
cluster(cluster_id, location_id=None, serve_nodes=None, default_storage_type=None, kms_key_name=None)
Factory to create a cluster associated with this instance.
For example:
from google.cloud.bigtable import Client
from google.cloud.bigtable import enums
# Assuming that there is an existing instance with `INSTANCE_ID`
# on the server already.
# to create an instance see
# 'https://cloud.google.com/bigtable/docs/creating-instance'
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
cluster_id = "clus-my-" + UNIQUE_SUFFIX
location_id = "us-central1-a"
serve_nodes = 1
storage_type = enums.StorageType.SSD
cluster = instance.cluster(
cluster_id,
location_id=location_id,
serve_nodes=serve_nodes,
default_storage_type=storage_type,
)
operation = cluster.create()
# We want to make sure the operation completes.
operation.result(timeout=100)
Parameters
cluster_id (str) – The ID of the cluster.
location_id (str) – (Creation Only) The location where this cluster’s nodes and storage reside. For best performance, clients should be located as close as possible to this cluster. For list of supported locations refer to https://cloud.google.com/bigtable/docs/locations
serve_nodes (int) – (Optional) The number of nodes in the cluster.
default_storage_type (int) – (Optional) The type of storage Possible values are represented by the following constants:
google.cloud.bigtable.enums.StorageType.SSD
.google.cloud.bigtable.enums.StorageType.HDD
, Defaults togoogle.cloud.bigtable.enums.StorageType.UNSPECIFIED
.kms_key_name (str) – (Optional, Creation Only) The name of the KMS customer managed encryption key (CMEK) to use for at-rest encryption of data in this cluster. If omitted, Google’s default encryption will be used. If specified, the requirements for this key are:
1. The Cloud Bigtable service account associated with the
project that contains the cluster must be granted the
`cloudkms.cryptoKeyEncrypterDecrypter` role on the
CMEK.
2. Only regional keys can be used and the region of the
CMEK key must match the region of the cluster.
3. All clusters within an instance must use the same CMEK
key.
Return type
Cluster
Returns
a cluster owned by this instance.
create(location_id=None, serve_nodes=None, default_storage_type=None, clusters=None)
Create this instance.
For example:
from google.cloud.bigtable import Client
from google.cloud.bigtable import enums
my_instance_id = "inst-my-" + UNIQUE_SUFFIX
my_cluster_id = "clus-my-" + UNIQUE_SUFFIX
location_id = "us-central1-f"
serve_nodes = 1
storage_type = enums.StorageType.SSD
production = enums.Instance.Type.PRODUCTION
labels = {"prod-label": "prod-label"}
client = Client(admin=True)
instance = client.instance(my_instance_id, instance_type=production, labels=labels)
cluster = instance.cluster(
my_cluster_id,
location_id=location_id,
serve_nodes=serve_nodes,
default_storage_type=storage_type,
)
operation = instance.create(clusters=[cluster])
# We want to make sure the operation completes.
operation.result(timeout=100)
NOTE: Uses the project
and instance_id
on the current
Instance
in addition to the display_name
.
To change them before creating, reset the values via
instance.display_name = 'New display name'
instance.instance_id = 'i-changed-my-mind'
before calling create()
.
Parameters
location_id (str) – (Creation Only) The location where nodes and storage of the cluster owned by this instance reside. For best performance, clients should be located as close as possible to cluster’s location. For list of supported locations refer to https://cloud.google.com/bigtable/docs/locations
serve_nodes (int) – (Optional) The number of nodes in the instance’s cluster; used to set up the instance’s cluster.
default_storage_type (int) – (Optional) The storage media type for persisting Bigtable data. Possible values are represented by the following constants:
google.cloud.bigtable.enums.StorageType.SSD
.google.cloud.bigtable.enums.StorageType.HDD
, Defaults togoogle.cloud.bigtable.enums.StorageType.UNSPECIFIED
.clusters (class:~[~google.cloud.bigtable.cluster.Cluster]) – List of clusters to be created.
Return type
Returns
The long-running operation corresponding to the create operation.
Raises
ValueError
if bothclusters
and one oflocation_id
,serve_nodes
anddefault_storage_type
are set.
delete()
Delete this instance.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance_to_delete = client.instance(instance_id)
instance_to_delete.delete()
Marks an instance and all of its tables for permanent deletion in 7 days.
Immediately upon completion of the request:
Billing will cease for all of the instance’s reserved resources.
The instance’s
delete_time
field will be set 7 days in the future.
Soon afterward:
- All tables within the instance will become unavailable.
At the instance’s delete_time
:
- The instance and all of its tables will immediately and irrevocably disappear from the API, and their data will be permanently deleted.
exists()
Check whether the instance already exists.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
instance_exists = instance.exists()
Return type
Returns
True if the table exists, else False.
classmethod from_pb(instance_pb, client)
Creates an instance instance from a protobuf.
For example:
from google.cloud.bigtable import Client
from google.cloud.bigtable_admin_v2.types import instance as data_v2_pb2
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
name = instance.name
instance_pb = data_v2_pb2.Instance(
name=name, display_name=INSTANCE_ID, type=PRODUCTION, labels=LABELS
)
instance2 = instance.from_pb(instance_pb, client)
Parameters
instance_pb (
instance.Instance
) – An instance protobuf object.client (
Client
) – The client that owns the instance.
Return type
Instance
Returns
The instance parsed from the protobuf response.
Raises
ValueError
if the instance name does not matchprojects/{project}/instances/{instance_id}
or if the parsed project ID does not match the project ID on the client.
get_iam_policy(requested_policy_version=None)
Gets the access control policy for an instance resource.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
policy = instance.get_iam_policy()
Parameters
requested_policy_version (int or
NoneType
) – Optional. The version of IAM policies to request. If a policy with a condition is requested without setting this, the server will return an error. This must be set to a value of 3 to retrieve IAM policies containing conditions. This is to prevent client code that isn’t aware of IAM conditions from interpreting and modifying policies incorrectly. The service might return a policy with version lower than the one that was requested, based on the feature syntax in the policy fetched.Return type
google.cloud.bigtable.policy.Policy
Returns
The current IAM policy of this instance
list_app_profiles()
Lists information about AppProfiles in an instance.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
app_profiles_list = instance.list_app_profiles()
Return type
:list:[~google.cloud.bigtable.app_profile.AppProfile]
Returns
A :list:[~google.cloud.bigtable.app_profile.AppProfile]. By default, this is a list of
AppProfile
instances.
list_clusters()
List the clusters in this instance.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
(clusters_list, failed_locations_list) = instance.list_clusters()
Return type
Returns
(clusters, failed_locations), where ‘clusters’ is list of
google.cloud.bigtable.instance.Cluster
, and ‘failed_locations’ is a list of locations which could not be resolved.
list_tables()
List the tables in this instance.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
tables_list = instance.list_tables()
Return type
list of
Table
Returns
The list of tables owned by the instance.
Raises
ValueError
if one of the returned tables has a name that is not of the expected format.
property name()
Instance name used in requests.
NOTE: This property will not change if instance_id
does not,
but the return value is not cached.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
instance_name = instance.name
The instance name is of the form
"projects/{project}/instances/{instance_id}"
Return type
Returns
Return a fully-qualified instance string.
reload()
Reload the metadata for this instance.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
instance.reload()
set_iam_policy(policy)
Sets the access control policy on an instance resource. Replaces any existing policy.
For more information about policy, please see documentation of class google.cloud.bigtable.policy.Policy
For example:
from google.cloud.bigtable import Client
from google.cloud.bigtable.policy import Policy
from google.cloud.bigtable.policy import BIGTABLE_ADMIN_ROLE
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
instance.reload()
new_policy = Policy()
new_policy[BIGTABLE_ADMIN_ROLE] = [Policy.service_account(service_account_email)]
policy_latest = instance.set_iam_policy(new_policy)
Parameters
policy (
google.cloud.bigtable.policy.Policy
) – A new IAM policy to replace the current IAM policy of this instanceReturn type
google.cloud.bigtable.policy.Policy
Returns
The current IAM policy of this instance.
property state()
state of Instance.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
instance_state = instance.state
Type
google.cloud.bigtable.enums.Instance.State
table(table_id, mutation_timeout=None, app_profile_id=None)
Factory to create a table associated with this instance.
For example:
from google.api_core import exceptions
from google.api_core import retry
from google.cloud.bigtable import Client
from google.cloud.bigtable import column_family
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
table = instance.table("table_my")
# Define the GC policy to retain only the most recent 2 versions.
max_versions_rule = column_family.MaxVersionsGCRule(2)
# Could include other retriable exception types
# Could configure deadline, etc.
predicate_504 = retry.if_exception_type(exceptions.DeadlineExceeded)
retry_504 = retry.Retry(predicate_504)
retry_504(table.create)(column_families={"cf1": max_versions_rule})
Parameters
Return type
Returns
The table owned by this instance.
test_iam_permissions(permissions)
Returns permissions that the caller has on the specified instance resource.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
instance.reload()
permissions = ["bigtable.clusters.create", "bigtable.tables.create"]
permissions_allowed = instance.test_iam_permissions(permissions)
Parameters
permissions (list) – The set of permissions to check for the
resource
. Permissions with wildcards (such as ‘*’ or ‘storage.*’) are not allowed. For more information see IAM Overview. Bigtable Permissions.Return type
Returns
A List(string) of permissions allowed on the instance
update()
Updates an instance within a project.
For example:
from google.cloud.bigtable import Client
client = Client(admin=True)
instance = client.instance(INSTANCE_ID)
display_name = "My new instance"
instance.display_name = display_name
instance.update()
NOTE: Updates any or all of the following values:
display_name
type
labels
To change a value before
updating, assign that values via
instance.display_name = 'New display name'
before calling update()
.
Return type
Returns
The long-running operation corresponding to the update operation.