new spec: mgc cli bucket policy basic usage

This patch adds specs covering the basic usage of the bucket policy
feature using the mgc cli.

The examples in here should include the same examples on the other
specs:

  - https://docs.magalu.cloud/docs/storage/object-storage/how-to/permissions/policies
  - https://github.com/MagaluCloud/s3-tester/blob/main/spec/091_bucket-policy_spec.sh

Author: fczuardi

docs/conftest.py

@@ -78,8 +78,9 @@ def mgc_path(default_profile):
     else:
         spec_dir = os.path.dirname(get_spec_path())
         path = os.path.join(spec_dir, default_profile.get(mgc_path_field_name))
-    if not os.path.isfile(path):
-        pytest.fail(f"The specified mgc_path '{path}' (absolute: {os.path.abspath(path)}) does not exist or is not a file.")
+    abspath = os.path.abspath(path) if path and os.path.isfile(path) else path
+    if not abspath:
+        pytest.fail(f"The specified mgc_path '{path}' (absolute: {abspath}) does not exist or is not a file.")
     return path
 
 @pytest.fixture
@@ -233,7 +234,7 @@ def bucket_with_one_object(request, s3_client):
     'object_prefix': "",
     'object_key_list': ['test-object-1.txt', 'test-object-2.txt']
 }])
-def bucket_with_many_objects(request, s3_client):
+def bucket_with_many_objects(request, s3_client, policy_wait_time):
     # this fixture accepts an optional request.param['object_key_list'] with a list of custom key names
     object_key_list = request.param['object_key_list']
     # and a string prefix to prepend on all objects
@@ -249,10 +250,7 @@ def bucket_with_many_objects(request, s3_client):
     # Yield the bucket name and object details to the test
     yield bucket_name, object_prefix, content
 
-    # Teardown: Delete the object and bucket after the test
-    for object_key in object_key_list:
-        delete_object_and_wait(s3_client, bucket_name, object_key)
-    delete_bucket_and_wait(s3_client, bucket_name)
+    delete_policy_and_bucket_and_wait(s3_client, bucket_name, policy_wait_time)
 
 
 
@@ -464,12 +462,12 @@ def bucket_with_one_object_policy(multiple_s3_clients, policy_wait_time, request
     yield bucket_name, object_key
 
     # Teardown: delete the bucket after the test
-    delete_policy_and_bucket_and_wait(client, bucket_name, policy_wait_time, request)
+    delete_policy_and_bucket_and_wait(client, bucket_name, policy_wait_time)
 
 
 
 
-@pytest.fixture
+@pytest.fixture(params=[{'number_clients': 1}])
 def multiple_s3_clients(request, test_params):
     """
     Creates multiple S3 clients based on the profiles provided in the test parameters.

docs/policy_cli_test.py

@@ -0,0 +1,152 @@
+# ---
+# jupyter:
+#   kernelspec:
+#     name: s3-specs
+#     display_name: S3 Specs
+#   language_info:
+#     name: python
+# ---
+
+# # Bucket Policy via MGC CLI
+#
+# Restringir determinadas ações passíveis de serem executadas em um bucket, ou
+# compartilhar acessos de leitura e escrita com outros usuários (Principals),
+# são exemplos de possibilidades que a funcionalidade de Bucket Policy (políticas
+# do conteiner) permitem.
+#
+# A configuração, remoção e atualização de políticas em um bucket, por documentos
+# de policy (arquivos JSON) pode ser feita via MGC CLI. Este é o assunto desta
+# especificação.
+#
+
+# + tags=["parameters"]
+config = "../params.example.yaml"
+config = "../params.yaml"
+config = "../params/br-ne1.yaml"
+# -
+
+# + {"jupyter": {"source_hidden": true}}
+import pytest
+import logging
+import subprocess
+from shlex import split
+from s3_helpers import (
+    run_example,
+)
+pytestmark = [pytest.mark.basic, pytest.mark.cli]
+# -
+# ## Como fazer
+
+# ### Listar os comandos disponíveis
+#
+# O manual de uso com os comandos disponíveis na CLI relacionados a Bucket Policy
+# pode ser consultado via terminal usando o comando abaixo:
+
+commands = [
+    "{mgc_path} object-storage buckets policy --help",
+]
+
+# + {"jupyter": {"source_hidden": true}}
+@pytest.mark.parametrize("cmd_template", commands)
+def test_cli_help_policy(cmd_template, mgc_path):
+    cmd = split(cmd_template.format(mgc_path=mgc_path))
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    assert result.returncode == 0, f"Command failed with error: {result.stderr}"
+    logging.debug(f"Output from {cmd_template}: {result.stdout}")
+    assert all(snippet in result.stdout for snippet in ["delete", "get", "set"])
+
+run_example(__name__, "test_cli_help_policy", config=config)
+# -
+
+# ### Documento de política válido
+#
+# Para fins de exemplificar o uso dos comandos, usaremos um documento JSON de política
+# válido bem simples, que habilita o download de todos os objetos (`*`) em um bucket
+# (`Resource`) para qualquer (`*`) usuário (`Principal`).
+
+# +
+@pytest.fixture
+def valid_simple_policy():
+    return """{
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Effect": "Allow",
+                "Principal": "*",
+                "Action": "s3:GetObject",
+                "Resource": "<bucket_name>/*"
+            }
+        ]
+    }"""
+# -
+
+# > **Nota:** Substitua `<bucket_name>` pelo nome do seu bucket.
+
+# ### Atribuir uma política a um bucket
+#
+# Para definir uma política de bucket usando a MGC CLI, utilize o comando:
+
+set_policy_commands = [
+    "{mgc_path} object-storage buckets policy set --dst {bucket_name} --policy '{policy_json_content}'",
+]
+
+# + {"jupyter": {"source_hidden": true}}
+@pytest.mark.parametrize("cmd_template", set_policy_commands)
+def test_cli_set_policy(cmd_template, active_mgc_workspace, mgc_path, valid_simple_policy, existing_bucket_name):
+    bucket_name = existing_bucket_name
+    policy = valid_simple_policy.replace("<bucket_name>", bucket_name)
+    logging.info(policy)
+    cmd = split(cmd_template.format(
+        mgc_path=mgc_path,
+        bucket_name=bucket_name,
+        policy_json_content=policy
+    ))
+    logging.info(f"{cmd}")
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    assert result.returncode == 0, f"Command failed with error: {result.stderr}"
+    logging.info(f"Output from {cmd_template}: {result.stdout}")
+
+run_example(__name__, "test_cli_set_policy", config=config)
+# -
+
+# ### Remover uma política de um bucket
+#
+# Para deletar uma política de bucket usando a MGC CLI, utilize o comando:
+
+delete_policy_commands = [
+    "{mgc_path} object-storage buckets policy delete --dst {bucket_name}",
+]
+
+# + {"jupyter": {"source_hidden": true}}
+from utils.policy import fixture_bucket_with_policy
+
+@pytest.mark.parametrize(
+    "cmd_template",
+    delete_policy_commands,
+)
+def test_cli_delete_policy(cmd_template, fixture_bucket_with_policy, active_mgc_workspace, mgc_path):
+    bucket_name, _policy_doc, _s3_clients, _object_prefix, _content = fixture_bucket_with_policy
+    cmd = split(cmd_template.format(mgc_path=mgc_path, bucket_name=bucket_name))
+    logging.info(f"{cmd}")
+    result = subprocess.run(cmd, capture_output=True, text=True)
+
+    assert result.returncode == 0, f"Command failed with error: {result.stderr}"
+    logging.info(f"Output from {cmd_template}: {result.stdout}")
+
+run_example(__name__, "test_cli_delete_policy", config=config)
+# -
+
+# ## Documentos relacionados
+#
+# Uma breve lista de outras referências sobre Bucket Policy
+#
+# - Docs Magalu Cloud: [Docs > Armazenamento > Object Storage > Como Fazer > Permissões > Bucket Policy](https://docs.magalu.cloud/docs/storage/object-storage/how-to/permissions/policies)
+# - Docs Magalu Cloud: [Docs > Armazenamento > Object Storage > Controle de Acesso de Dados > Bucket Policy](https://docs.magalu.cloud/docs/storage/object-storage/access-control/bucket_policy_overview/)
+# - s3-specs: [python/boto3 policies spec 1](https://magalucloud.github.io/s3-specs/runs/profiles_policies_test_br-ne1.html)
+# - s3-specs: [python/boto3 policies spec 2](https://magalucloud.github.io/s3-specs/runs/policies_test_test_br-ne1.html)
+# - s3-tester (specs legadas): [legacy s3-tester spec id:091](https://github.com/MagaluCloud/s3-tester/blob/main/spec/091_bucket-policy_spec.sh)
+# - AWS S3: [Bucket Policies for Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html)
+# - AWS S3: [Bucket policies](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-example-bucket-policies.html)
+

docs/s3_helpers.py

@@ -108,12 +108,11 @@ def delete_all_objects_and_wait(s3_client, bucket_name):
         for obj in response['Contents']:
             delete_object_and_wait(s3_client, bucket_name, obj['Key'])
 
-def delete_policy_and_bucket_and_wait(s3_client, bucket_name, policy_wait_time, request):
+def delete_policy_and_bucket_and_wait(s3_client, bucket_name, policy_wait_time):
     retries = 3
     sleeptime = 5
     for attempt_number in range(retries):   
         try:
-            change_policies_json(bucket_name, {"policy_dict": request.param['policy_dict'], "actions": ["s3:GetObjects", "*"], "effect": "Allow"}, tenants=["*"])
             logging.info(f"deleting policy of bucket {bucket_name}...")
             s3_client.delete_bucket_policy(Bucket=bucket_name)
             break

docs/utils/policy.py

@@ -0,0 +1,38 @@
+import logging
+import pytest
+
+allow_get_object_policy = """{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": "*",
+            "Action": "s3:GetObject",
+            "Resource": "<bucket_name>/*"
+        }
+    ]
+}"""
+
+
+# This fixture accepts indirect arguments in a dict:
+#   policy_doc: is a string with a json and <bucket_name>
+# on the places that will be replaced with the name
+# of the generated bucket
+#
+# This fixture depends on the bucket_with_many_objects
+# fixture so if your test needs custom onject keys you
+# need to indirect pass the arguments for that dependency
+#
+# This fixture depends on the multiple_s3_clients
+# fixture so if your test needs custom number of clients you
+# need to indirect pass the arguments for that dependency
+@pytest.fixture(params=[{'policy_doc': allow_get_object_policy}])
+def fixture_bucket_with_policy(request, multiple_s3_clients, bucket_with_many_objects):
+    s3_clients = multiple_s3_clients
+    bucket_owner_client = s3_clients[0]
+    bucket_name, object_prefix, content = bucket_with_many_objects
+    policy_template = request.param['policy_doc']
+    policy_doc = policy_template.replace("<bucket_name>", bucket_name)
+    bucket_owner_client.put_bucket_policy(Bucket=bucket_name, Policy = policy_doc)
+
+    return bucket_name, policy_doc, s3_clients, object_prefix, content