[DPE-4196] Rebase the plugin refactor (#520)

There were several changes on the config-changed logic and made this
rebase rather complex. I am making a PR to the main refactor branch so
we can look at it more carefully before having it all together.

.github/workflows/ci.yaml

@@ -24,22 +24,75 @@ jobs:
     timeout-minutes: 10
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Install tox & poetry
         run: |
           pipx install tox
           pipx install poetry
       - name: Run tests
         run: tox run -e unit
 
+  terraform-test:
+    name: Terraform - Lint and Simple Deployment
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: lint charm module
+        run: |
+          pushd ./terraform
+          terraform init
+          terraform fmt
+          terraform validate
+
+          pushd ./tests
+          terraform init
+          terraform fmt
+          terraform validate
+          popd
+          popd
+
+      - name: run checks - prepare
+        run: |
+          sudo snap install juju --channel=3.6/beta --classic
+          sudo snap install juju-wait --channel=latest/stable --classic
+          sudo snap install jq
+
+      - name: LXD setup
+        run: |
+          sudo snap refresh lxd --channel=latest/stable
+          sudo adduser "$USER" 'lxd'
+          # `newgrp` does not work in GitHub Actions; use `sg` instead
+          sg 'lxd' -c "lxd waitready"
+          sg 'lxd' -c "lxd init --auto"
+          sg 'lxd' -c "lxc network set lxdbr0 ipv6.address none"
+          sudo iptables -F FORWARD
+          sudo iptables -P FORWARD ACCEPT
+
+      - name: Juju setup
+        run: |
+          sg 'lxd' -c "juju bootstrap 'localhost' --config model-logs-size=10G"
+          juju model-defaults logging-config='<root>=INFO; unit=DEBUG'
+          juju add-model test
+
+      - name: Terraform deploy
+        run: |
+          pushd ./terraform/tests/
+          TF_VAR_model_name="test" terraform apply -target null_resource.simple_deployment_juju_wait_deployment -auto-approve
+          popd
+
 
   lib-check:
     name: Check libraries
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - run: |

.gitignore

@@ -16,3 +16,50 @@ cloudinit-userdata.yaml
 # Moving to Poetry, we do not need this file to be pushed any longer
 /requirements.txt
 /requirements-last-build.txt
+
+########################################################
+#
+# Terraform .gitignore
+#
+########################################################
+
+
+# Local .terraform directories
+**/.terraform/*
+*.terraform.lock.hcl
+
+# .tfstate files
+*.tfstate
+*.tfstate.*
+
+# Crash log files
+crash.log
+crash.*.log
+
+# Generated files
+*.key
+credentials*
+
+# Exclude all .tfvars files, which are likely to contain sensitive data, such as
+# password, private keys, and other secrets. These should not be part of version 
+# control as they are data points which are potentially sensitive and subject 
+# to change depending on the environment.
+*.tfvars
+*.tfvars.json
+
+# Ignore override files as they are usually used to override resources locally and so
+# are not checked in
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json
+
+# Include override files you do wish to add to version control using negated pattern
+# !example_override.tf
+
+# Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan
+# example: *tfplan*
+
+# Ignore CLI configuration files
+.terraformrc
+terraform.rc

config.yaml

@@ -36,3 +36,13 @@ options:
     default: true
     type: boolean
     description: Enable opensearch-knn
+
+  profile:
+    type: string
+    default: "production"
+    description: |
+      Profile representing the scope of deployment, and used to tune resource allocation.
+      Allowed values are: "production", "staging" or "testing"
+      Production will tune opensearch for maximum performance while default will tune for
+      minimal running performance.
+      Performance tuning is described on: https://opensearch.org/docs/latest/tuning-your-cluster/performance/

docs/how-to/h-deploy-lxd.md

@@ -150,6 +150,10 @@ juju model-config --file=./cloudinit-userdata.yaml
 
 ## Deploy OpenSearch
 
+[note]
+**Note:** Charmed OpenSearch supports performance profile. It is recommended in a single host deployment with LXD to use the testing profile, which will only consume 1G RAM per container.
+[/note]
+
 To deploy OpenSearch, run
 ```shell
 juju deploy opensearch --channel 2/edge

docs/how-to/h-integrate.md

@@ -1,4 +1,4 @@
-# How to integrate OpenSearch with your charm
+# How to integrate OpenSearch with an application
 
 [Integrations](https://juju.is/docs/juju/relation) (formerly "relations") are connections between two applications with compatible endpoints. These connections simplify creating and managing users, passwords, and other shared data.
 
@@ -27,7 +27,7 @@ The Charmed OpenSearch provides the `opensearch_client` interface to allow other
 To integrate your client application you must define the `opensearch_client` interface in your charm's `metadata.yaml` file.
 
 ```yaml
-provides:
+requires:
   opensearch:
     interface: opensearch_client
 ```

docs/how-to/h-large-deployment.md

@@ -45,6 +45,7 @@ When no roles are set on the `roles` config option of the opensearch application
 There are currently two ways for users to set roles in an application: at deploy time, or via a config change. Note that a role change will effectively trigger a rolling restart of the OpenSearch application.
 
 To set roles at deploy time, run
+
  ```none
  juju deploy opensearch -n 3 --config roles="cluster_manager,data,ml"
 ```
@@ -63,12 +64,25 @@ The cluster will consist of multiple integrated juju applications (clusters) wit
 
 ### Deploy the clusters
 
+[note type="caution"]
+**Caution**: Charmed OpenSearch supports performance profiles and will have different RAM consumption according to the profile chosen:
+
+* `production`: consumes 50% of the RAM available, up to 32G
+* `staging`: consumes 25% of the RAM available, up to 32G
+* `testing`: consumes 1G of RAM
+
+The configuration defaults to `production`, but for the examples below, testing will be chosen as it is assumed the deployment happens on a single LXD cluster.
+
+[/note]
+
 1. First, deploy the orchestrator app.
+
     ```shell
     juju deploy -n 3 \
         opensearch main \
         --config cluster_name="app" \
-        --channel 2/edge
+        --channel 2/edge \
+        --config profile="testing"
     ```
 
     As a reminder, since we did not set any role to this application, the operator will assign each node the `cluster_manager,coordinating_only,data,ingest,ml` roles.
@@ -80,8 +94,9 @@ The failover app will take over the orchestration of the fleet in the events whe
         opensearch failover \
         --config cluster_name="app" \
         --config init_hold="true" \
-        --config roles="cluster_manager" 
-        --channel 2/edge
+        --config roles="cluster_manager"  \
+        --channel 2/edge \
+        --config profile="testing"
     ```
 
    The failover nodes are not required for a basic deployment of OpenSearch. They are however highly recommended for production deployments to ensure high availability and fault tolerance.
@@ -98,7 +113,8 @@ The failover app will take over the orchestration of the fleet in the events whe
          --config cluster_name="app" \
          --config roles="data.hot" \
          --config init_hold="true" \
-         --channel 2/edge 
+         --channel 2/edge \
+         --config profile="testing"
    ```
 
 4. We also need to deploy a TLS operator to enable TLS encryption for the cluster. We will deploy the `self-signed-certificates` charm to provide self-signed certificates for the cluster.

docs/how-to/h-minor-upgrade.md

@@ -114,10 +114,25 @@ The action will ensure and check the health of OpenSearch and determine if the c
 
 ## Initiate the upgrade
 
+[note type="caution"]
+**Caution**: Charmed OpenSearch supports performance profiles and will have different RAM consumption according to the profile chosen:
+
+* `production`: consumes 50% of the RAM available, up to 32G
+* `staging`: consumes 25% of the RAM available, up to 32G
+* `testing`: consumes 1G of RAM
+
+In case your charm is running on revision prior to `185`, the `testing` profile will be your default value. Ensure you have it set at upgrade and then feel free to switch to another profile that is more suitable to your use-case.
+
+[/note]
+
 Use the juju refresh command to trigger the charm upgrade process. You have control over what upgrade you want to apply:
 - You can upgrade the charm to the latest revision available in the charm store for a specific channel, in this case, the edge channel:
 
     ```shell
+    # If your charm is running a revision prior to 185, then set the profile explicitly:
+    juju refresh opensearch --channel 2/edge --config profile="testing"
+
+    # Otherwise, just refresh
     juju refresh opensearch --channel 2/edge
     ```
 

docs/how-to/h-rotate-tls-ca-certificates.md

@@ -78,7 +78,10 @@ juju run manual-tls-certificates/leader provide-certificate \
   unit-name="<unit-name>"
 ```
 
-Once the new certificate is provided to the OpenSearch cluster, the OpenSearch cluster will automatically detect the new CA certificate and trigger a CA rotation on the node which results in new CSRs being generated. You can then sign the new CSRs using the new CA certificate and provide the new certificates to the OpenSearch node using the `manual-tls operator`.
+Once the new certificate is provided to the OpenSearch cluster, the OpenSearch cluster will automatically detect the new CA certificate and trigger a CA rotation on the node which results in new CSRs being generated. You can then sign the new CSRs using the new CA certificate and provide the new certificates to the OpenSearch node using the `manual-tls operator`. 
+[note  type="caution"]
+The distribution of certificates must follow a specific order. The leader unit is first followed by the remaining nodes.
+[/note]
 
 This process needs to be repeated for each unit in the OpenSearch cluster. Once all the units have the new CA certificate, the OpenSearch cluster will update the TLS certificates on the nodes, either by reloading them via API or by triggering a rolling restart of the OpenSearch cluster. Restarting to apply the new TLS certificates is only required if the issuer, the subject or the subject alternative names (sans) of the new certificate are different than before. If they stay the same, the new TLS certificates can be reloaded on the fly.
 

docs/overview.md

@@ -54,15 +54,14 @@ This documentation follows the [Diataxis Framework](https://canonical.com/blog/d
 | 2 | t-horizontal-scaling | [6. Scale horizontally](/t/9720)  |
 | 2 | t-clean-up | [7. Clean up the environment](/t/9726) |
 | 1 | how-to | [How To]() |
-| 2 | h-deploy-lxd | [Deploy on LXD](/t/14575) |
-| 2 | h-large-deployment | [Launch a large deployment](/t/15573) |
+| 2 | h-deploy | [Deploy]() |
+| 3 | h-deploy-lxd | [Deploy on LXD](/t/14575) |
+| 3 | h-large-deployment | [Launch a large deployment](/t/15573) |
+| 2 | h-tls| [TLS encryption]() |
+| 3 | h-enable-tls | [Enable TLS encryption](/t/14783) |
+| 3 | h-rotate-tls-ca-certificates   | [Rotate TLS/CA certificates](/t/15422) |
 | 2 | h-horizontal-scaling  | [Scale horizontally](/t/10994) |
-| 2 | h-integrate | [Integrate with your charm](/t/15333) |
-| 2 | h-enable-tls | [Enable TLS encryption](/t/14783) |
-| 2 | h-rotate-tls-ca-certificates   | [Rotate TLS/CA certificates](/t/15422) |
-| 2 | h-enable-monitoring | [Enable monitoring](/t/14560) |
-| 2 | h-load-testing | [Perform load testing](/t/13987) |
-| 2 | h-attached-storage| [Recover from attached storage](/t/15616) |
+| 2 | h-integrate | [Integrate with an application](/t/15333) |
 | 2 | h-backups | [Back up and restore]() |
 | 3 | h-configure-s3 | [Configure S3](/t/14097) |
 | 3 | h-create-backup | [Create a backup](/t/14098) |
@@ -71,6 +70,9 @@ This documentation follows the [Diataxis Framework](https://canonical.com/blog/d
 | 2 | h-upgrade | [Upgrade]() |
 | 3 | h-minor-upgrade | [Perform a minor upgrade](/t/14141) |
 | 3 | h-minor-rollback | [Perform a minor rollback](/t/14142) |
+| 2 | h-load-testing | [Perform load testing](/t/13987) |
+| 2 | h-attached-storage| [Recover from attached storage](/t/15616) |
+| 2 | h-enable-monitoring | [Enable monitoring](/t/14560) |
 | 1 | reference | [Reference]() |
 | 2 | release-notes| [Release notes]() |
 | 3 | revision-168| [Revision 168](/t/14050) |

docs/tutorial/t-deploy-opensearch.md

@@ -4,8 +4,13 @@
 
 To deploy Charmed OpenSearch, all you need to do is run the following command:
 
+[note]
+**Note:** Charmed OpenSearch supports performance profile. It is recommended in a single host deployment with LXD to use the testing profile, which will only consume 1G RAM per container.
+[/note]
+
+
 ```shell
-juju deploy opensearch -n 3 --channel 2/beta
+juju deploy opensearch -n 3 --channel 2/beta --config profile="testing"
 ```
 
 [note]

lib/charms/data_platform_libs/v0/data_interfaces.py

@@ -331,7 +331,7 @@ def _on_topic_requested(self, event: TopicRequestedEvent):
 
 # Increment this PATCH version before using `charmcraft publish-lib` or reset
 # to 0 if you are raising the major API version
-LIBPATCH = 39
+LIBPATCH = 40
 
 PYDEPS = ["ops>=2.0.0"]
 
@@ -391,6 +391,10 @@ class IllegalOperationError(DataInterfacesError):
     """To be used when an operation is not allowed to be performed."""
 
 
+class PrematureDataAccessError(DataInterfacesError):
+    """To be raised when the Relation Data may be accessed (written) before protocol init complete."""
+
+
 ##############################################################################
 # Global helpers / utilities
 ##############################################################################
@@ -1453,6 +1457,8 @@ def _on_relation_changed_event(self, event: RelationChangedEvent) -> None:
 class ProviderData(Data):
     """Base provides-side of the data products relation."""
 
+    RESOURCE_FIELD = "database"
+
     def __init__(
         self,
         model: Model,
@@ -1618,6 +1624,15 @@ def _fetch_my_specific_relation_data(
     def _update_relation_data(self, relation: Relation, data: Dict[str, str]) -> None:
         """Set values for fields not caring whether it's a secret or not."""
         req_secret_fields = []
+
+        keys = set(data.keys())
+        if self.fetch_relation_field(relation.id, self.RESOURCE_FIELD) is None and (
+            keys - {"endpoints", "read-only-endpoints", "replset"}
+        ):
+            raise PrematureDataAccessError(
+                "Premature access to relation data, update is forbidden before the connection is initialized."
+            )
+
         if relation.app:
             req_secret_fields = get_encoded_list(relation, relation.app, REQ_SECRET_FIELDS)
 
@@ -3290,6 +3305,8 @@ class KafkaRequiresEvents(CharmEvents):
 class KafkaProviderData(ProviderData):
     """Provider-side of the Kafka relation."""
 
+    RESOURCE_FIELD = "topic"
+
     def __init__(self, model: Model, relation_name: str) -> None:
         super().__init__(model, relation_name)
 
@@ -3539,6 +3556,8 @@ class OpenSearchRequiresEvents(CharmEvents):
 class OpenSearchProvidesData(ProviderData):
     """Provider-side of the OpenSearch relation."""
 
+    RESOURCE_FIELD = "index"
+
     def __init__(self, model: Model, relation_name: str) -> None:
         super().__init__(model, relation_name)
 

lib/charms/opensearch/v0/constants_charm.py

@@ -119,6 +119,6 @@
 # User-face Backup ID format
 OPENSEARCH_BACKUP_ID_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
 
-
 S3_REPO_BASE_PATH = "/"
 S3_RELATION = "s3-credentials"
+PERFORMANCE_PROFILE = "profile"