docs(storage): add some IAM examples

Cargo.toml

@@ -348,11 +348,12 @@ tokio-test     = { default-features = false, version = "0.4" }
 
 # Local packages used as dependencies
 auth                          = { version = "0.22.4", path = "src/auth", package = "google-cloud-auth" }
-google-cloud-auth             = { version = "0.22.4", path = "src/auth", package = "google-cloud-auth" }
+google-cloud-auth             = { version = "0.22.4", path = "src/auth" }
 gax                           = { version = "0.24", path = "src/gax", package = "google-cloud-gax" }
-google-cloud-gax              = { version = "0.24", path = "src/gax", package = "google-cloud-gax" }
+google-cloud-gax              = { version = "0.24", path = "src/gax" }
 gaxi                          = { version = "0.5.2", path = "src/gax-internal", package = "google-cloud-gax-internal" }
 iam_v1                        = { version = "0.4.4", path = "src/generated/iam/v1", package = "google-cloud-iam-v1" }
+google-cloud-iam-v1           = { version = "0.4.4", path = "src/generated/iam/v1" }
 location                      = { version = "0.4.4", path = "src/generated/cloud/location", package = "google-cloud-location" }
 longrunning                   = { version = "0.25.4", path = "src/generated/longrunning", package = "google-cloud-longrunning" }
 google-cloud-longrunning      = { version = "0.25.4", path = "src/generated/longrunning", package = "google-cloud-longrunning" }
@@ -363,6 +364,7 @@ google-cloud-wkt              = { version = "0.5.4", path = "src/wkt", package =
 api                           = { version = "0.4.4", path = "src/generated/api/types", package = "google-cloud-api" }
 cloud_common                  = { version = "0.4.4", path = "src/generated/cloud/common", package = "google-cloud-common" }
 gtype                         = { version = "0.4.4", path = "src/generated/type", package = "google-cloud-type" }
+google-cloud-type             = { version = "0.4.4", path = "src/generated/type" }
 grafeas                       = { version = "0.4.4", path = "src/generated/grafeas/v1", package = "google-cloud-grafeas-v1" }
 logging_type                  = { version = "0.4.4", path = "src/generated/logging/type", package = "google-cloud-logging-type" }
 rpc                           = { version = "0.4.4", path = "src/generated/rpc/types", package = "google-cloud-rpc" }

src/storage/examples/Cargo.toml

@@ -30,13 +30,16 @@ bytes.workspace                = true
 clap                           = { workspace = true, features = ["derive", "std"] }
 futures.workspace              = true
 google-cloud-gax.workspace     = true
+google-cloud-iam-v1.workspace  = true
 google-cloud-lro.workspace     = true
-google-cloud-wkt.workspace     = true
 google-cloud-storage.workspace = true
+google-cloud-type.workspace    = true
+google-cloud-wkt.workspace     = true
 rand.workspace                 = true
 tokio                          = { workspace = true, features = ["macros"] }
-tracing.workspace              = true
 tracing-subscriber             = { workspace = true, features = ["fmt", "std"] }
+tracing.workspace              = true
 
 [features]
-run-integration-tests = []
+run-integration-tests     = []
+skipped-integration-tests = []

src/storage/examples/src/buckets.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+pub mod add_bucket_conditional_iam_binding;
+pub mod add_bucket_iam_member;
 pub mod add_bucket_owner;
 pub mod change_default_storage_class;
 pub mod create_bucket;
@@ -37,10 +39,13 @@ pub mod print_bucket_acl_for_user;
 pub mod print_bucket_website_configuration;
 pub mod remove_bucket_owner;
 pub mod remove_retention_policy;
+#[allow(dead_code)]
+pub mod set_bucket_public_iam;
 pub mod set_lifecycle_abort_multipart_upload;
 pub mod set_public_access_prevention_enforced;
 pub mod set_public_access_prevention_inherited;
 pub mod set_public_access_prevention_unspecified;
 pub mod set_retention_policy;
+pub mod view_bucket_iam_members;
 pub mod view_lifecycle_management_configuration;
 pub mod view_versioning_status;

src/storage/examples/src/buckets/add_bucket_conditional_iam_binding.rs

@@ -0,0 +1,56 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_add_bucket_conditional_iam_binding]
+use google_cloud_iam_v1::model::{Binding, GetPolicyOptions};
+use google_cloud_storage::client::StorageControl;
+use google_cloud_type::model::Expr;
+
+pub async fn sample(
+    client: &StorageControl,
+    bucket_id: &str,
+    service_account: &str,
+) -> anyhow::Result<()> {
+    let mut policy = client
+        .get_iam_policy()
+        .set_resource(format!("projects/_/buckets/{bucket_id}"))
+        .set_options(GetPolicyOptions::new().set_requested_policy_version(3))
+        .send()
+        .await?;
+    let condition = Expr::new()
+        .set_expression(format!(
+            r#"resource.name.startsWith("projects/_/buckets/{bucket_id}/objects/prefix-a-")"#
+        ))
+        .set_title("A service account can read prefix-a-*")
+        .set_description(format!(
+            "Allows {service_account} read access to objects starting with `prefix-a-`"
+        ));
+    let binding = Binding::new()
+        .set_role("roles/storage.objectViewer")
+        .set_members([format!("serviceAccount:{service_account}")])
+        .set_condition(condition);
+    policy.version = 3;
+    policy.bindings.push(binding);
+    let updated_policy = client
+        .set_iam_policy()
+        .set_resource(format!("projects/_/buckets/{bucket_id}"))
+        .set_policy(policy)
+        .send()
+        .await?;
+    println!(
+        "Successfully added conditional IAM binding to bucket {bucket_id}: {updated_policy:?}"
+    );
+    Ok(())
+}
+// [END storage_add_bucket_conditional_iam_binding]

src/storage/examples/src/buckets/add_bucket_iam_member.rs

@@ -0,0 +1,44 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_add_bucket_iam_member]
+use google_cloud_iam_v1::model::Binding;
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(
+    client: &StorageControl,
+    bucket_id: &str,
+    role: &str,
+    member: &str,
+) -> anyhow::Result<()> {
+    let mut policy = client
+        .get_iam_policy()
+        .set_resource(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    policy
+        .bindings
+        .push(Binding::new().set_role(role).set_members([member]));
+    let updated_policy = client
+        .set_iam_policy()
+        .set_resource(format!("projects/_/buckets/{bucket_id}"))
+        .set_policy(policy)
+        .send()
+        .await?;
+    println!(
+        "Successfully added binding for {member} to bucket {bucket_id} policy: {updated_policy:?}"
+    );
+    Ok(())
+}
+// [END storage_add_bucket_iam_member]

src/storage/examples/src/buckets/set_bucket_public_iam.rs

@@ -0,0 +1,43 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_set_bucket_public_iam]
+use google_cloud_iam_v1::model::Binding;
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    let mut policy = client
+        .get_iam_policy()
+        .set_resource(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    policy.bindings.push(
+        Binding::new()
+            .set_role("roles/storage.objectViewer")
+            .set_members(vec!["allUsers".to_string()]),
+    );
+    let updated_policy = client
+        .set_iam_policy()
+        .set_resource(format!("projects/_/buckets/{bucket_id}"))
+        .set_policy(policy)
+        .send()
+        .await?;
+    println!(
+        "Successfully set public IAM policy for bucket {}",
+        bucket_id
+    );
+    println!("The updated policy is: {:?}", updated_policy);
+    Ok(())
+}
+// [END storage_set_bucket_public_iam]

src/storage/examples/src/buckets/view_bucket_iam_members.rs

@@ -0,0 +1,27 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START storage_view_bucket_iam_members]
+use google_cloud_storage::client::StorageControl;
+
+pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
+    let policy = client
+        .get_iam_policy()
+        .set_resource(format!("projects/_/buckets/{bucket_id}"))
+        .send()
+        .await?;
+    println!("IAM policy for bucket {}: {:?}", bucket_id, policy);
+    Ok(())
+}
+// [END storage_view_bucket_iam_members]

src/storage/examples/src/lib.rs

@@ -168,6 +168,31 @@ pub async fn run_bucket_examples(buckets: &mut Vec<String>) -> anyhow::Result<()
     tracing::info!("running create_bucket_hierarchical_namespace example");
     buckets::create_bucket_hierarchical_namespace::sample(&client, &project_id, &id).await?;
 
+    // Use a new bucket to avoid clashing policies from the previous examples.
+    let id = random_bucket_id();
+    buckets.push(id.clone());
+    tracing::info!("running create_bucket_hierarchical_namespace example [2]");
+    buckets::create_bucket_hierarchical_namespace::sample(&client, &project_id, &id).await?;
+    tracing::info!("running add_bucket_iam_member example");
+    buckets::add_bucket_iam_member::sample(
+        &client,
+        &id,
+        "roles/storage.objectViewer",
+        &format!("serviceAccount:{service_account}"),
+    )
+    .await?;
+    #[cfg(feature = "skipped-integration-tests")]
+    {
+        // Skip, the internal Google policies prevent granting public access to
+        // any buckets in our test projects.
+        tracing::info!("running set_bucket_public_iam example");
+        buckets::set_bucket_public_iam::sample(&client, &id).await?;
+    }
+    tracing::info!("running add_bucket_conditional_iam_binding example");
+    buckets::add_bucket_conditional_iam_binding::sample(&client, &id, &service_account).await?;
+    tracing::info!("running view_bucket_iam_members example");
+    buckets::view_bucket_iam_members::sample(&client, &id).await?;
+
     Ok(())
 }