Skip to main content
Version: 1.1.0

Using a9s Logme2

This chapter describes how to interact with a9s Logme2 using the Kubernetes API.

Pre-requisite​

Choose your Kubernetes Environment​

As a developer, you have the flexibility to choose between using an existing Kubernetes cluster or creating a new one for your testing and development needs.

If you choose to create a new cluster on your development machine, you can use kind for this purpose. Simply execute the following command:

kind create cluster --name=consumer-cluster
note

This cluster, referred to as the consumer cluster, does not run anything special; its true power lies in its seamless integration with a9s Data Services. Developers can effortlessly interact with the Data Services using Kubernetes Custom Resources provided by the a9s Kubernetes API.

Create Bindings to Data Services​

note

Prior to creating new bindings, it is essential to confirm that they do not already exist. This verification process helps avoid unnecessary execution of commands. To ascertain the presence of bindings, please execute the following commands within a terminal session connected to your designated Kubernetes cluster.

kubectl get logme2instances.anynines.com

kubectl get servicebindings.anynines.com

kubectl get backups.anynines.com

kubectl get restores.anynines.com

If bindings exist you should not get the following error

error: the server doesn't have a resource type "<resource-name>"

If there are no existing bindings from the tenant cluster to a9s Data Services, you can create them by following the provided instructions.

Binding a Tenant Cluster​

We use kube-bind to bind a9s Kubernetes API into tenant cluster.

In order to utilize the kubectl bind command, you'll need to have the kubectl-bind binary installed and properly added to your system's path.

Download the appropriate kubectl-bind binary for your system's architecture from the provided options:

Download links:

Open the folder to where you downloaded the file and open a terminal window

I. Create a new directory to add to your PATH environment variable

 mkdir <installation-directory>/bin

II. Give the folder executable permission

chmod 755 <installation-directory>/bin

III. Copy the binary to the newly created folder

cp ./kubectl-bind <installation-directory>/bin

IV. Add the path to PATH environment variable

export PATH=$PATH:<installation-directory>/bin

V. If everything is configured correctly you should see some output when you run the following command

kubectl bind
caution

When running the command above, you might encounter the error message:

'kubectI-bind' can't be opened because Apple cannot check it for malicious software.

To resolve this error, you can follow the instructions provided here.

  1. Replace <A9S-BIND-BACKEND-URL> with the domain provided to you by the platform operators.

    kubectl bind http://<A9S-BIND-BACKEND-URL>:443/export --konnector-image=public.ecr.aws/w5n9a2g2/anynines/konnector:v0.4.0-pre-release3

  2. Authenticate with provided URL using your OIDC credentials. Grant access in browser and respond Yes in the terminal to grant required access. Bind one at a time by using kubectl bind and logging into the browser.

    You can select the service to bind by using the web UI, as shown in the following image:

    Bind an a9s Data Service using the web UI

You are now all set to apply Kubernetes Custom Resources supported by the a9s Kubernetes API.

Create a Logme2 Service Instance​

To provision a Logme2 database, apply a Service Instance Claim. Before applying the Service Instance Claim, make sure to configure the required fields: service and plan.

The supported values for service and plan can be found in the following tables:

Supported Services​

Service nameDescription
a9s-logme2a9s LogMe2 enables on demand provisioning of a pre-configured OpenSearch and Fluentd Stack.

Supported Plans​

Plan nameDescription
logme-single-small-sslA single node with small resources.
logme-cluster-small-sslA cluster of 3 nodes with small resources.
note

All plan names having -ssl at the end show they support SSL.

caution

Migrations from single to clustered instances or from clustered to single instances are not supported.

Create a Logme2 Kubernetes Object​

To set up a Logme2 Kubernetes Object, simply replace the placeholder values denoted by < > in the provided yaml. Kindly select one of the supported values for spec.service and spec.plan.

Optional: To set up a clustered Logme2 with small specifications, apply the yaml manifest provided in the Example tab below. Feel free to modify the fields in order to create a different type of Logme2 database tailored to your requirements.

  apiVersion: anynines.com/v1
  kind: Logme2Instance
  metadata:
    name: <name>
    namespace: <namespace>
  spec:
    service: <service-name>
    plan: <plan-name>
    compositionRef:
      name: a9s-logme2

Applying this Kubernetes yaml manifest is as straightforward as working with any default Kubernetes resource.

kubectl apply -f <filename.yaml>

After applying the manifest, please allow some time for the remote resources to be deployed. If you've deployed the provided example, you should observe an output similar to the following:

kubectl get logme2instances.anynines.com
NAME                          SYNCED   READY   CONNECTION-SECRET   AGE
example-logme2-instance       True     True                        9m

You can also obtain additional information about the status of Logme2 Objects using the following command:

kubectl describe logme2instances.anynines.com
Name:         example-logme2-instance
Namespace:    default
...
Status:
  Conditions:
    Last Transition Time:  2023-08-07T09:57:49Z
    Reason:                ReconcileSuccess
    Status:                True
    Type:                  Synced
    Last Transition Time:  2023-08-07T10:04:11Z
    Reason:                Available
    Status:                True
    Type:                  Ready
  Managed:
    Conditions:
      Last Transition Time:  2023-08-07T09:57:50Z
      Reason:                ReconcileSuccess
      Status:                True
      Type:                  Synced
      Last Transition Time:  2023-08-07T10:04:00Z
      Reason:                Available
      Status:                True
      Type:                  Ready
    Created At:              2023-08-07T09:57:50.556Z
    Provisioned At:          2023-08-07T10:03:40.445Z
    State:                   provisioned
    Updated At:              2023-08-07T10:03:40.500Z
info

No Logme2 pod is running locally in the consumer cluster.

Behind the scenes the Custom Resources synced up to the a9s Data Service platform which ensures the database is provisioned and healthy. The status information reflecting the database status synced back to the tenant cluster to signify service readiness.

Bind an Application to a Logme2 Database​

The ServiceBinding Custom Resource is all that you need to quickly start using the database. To target a specific Logme2 instance, set the spec.instanceRef field.

Optional: If you've followed the example from the previous step, where we create a Logme2 Kubernetes Object, you can now proceed to apply the yaml manifest provided in the Example tab below. This will bind the previously created Logme2 instance.

  apiVersion: anynines.com/v1
  kind: ServiceBinding
  metadata:
    name: <name>
    namespace: <namespace>
  spec:
    instanceRef: <logme2-instance-name>
    serviceInstanceType: logme2
    compositionRef:
      name: a9s-servicebinding

After a few seconds, the ServiceBinding will be ready. You can then access the credentials and network details required for database connectivity by describing the Secret that was automatically created. The Data Service automation generates a Secret, named {service-binding-name}-creds, in the same namespace as the ServiceBinding.

For instance, if you have already applied the provided examples, upon the successful deployment of the ServiceBinding, you can access credentials and network details by describing the corresponding Kubernetes Secret using the following command:

kubectl get secret sample-logme2-servicebinding-creds -o yaml
apiVersion: v1
data:
  cacrt: <base64 encoded value>
  host: <base64 encoded value>
  password: <base64 encoded value>
  syslog_drain_url: <base64 encoded value>
  username: <base64 encoded value>
...

Backup a Logme2 Database​

The a9s platform provides an easy way to create backups and restore if needed. You can use the Kubernetes Custom Resource Backup from the API group anynines.com to create backups of Data Service Instances. To do this, simply target the specific Data Service Instance you want to back up, as shown in the following yaml manifest:

  apiVersion: anynines.com/v1
  kind: Backup
  metadata:
    name: <name>
    namespace: <namespace>
  spec:
    instanceRef: <logme2-instance-name>
    serviceInstanceType: logme2
    compositionRef:
      name: a9s-backup

And then apply the yaml manifest:

kubectl apply -f <filename.yaml>

You can inspect the status of the backup to determine when it is complete, similar to how we did it for the Logme2 instance, using the following command:

kubectl get backup.anynines.com -o yaml

You can observe the status transition from queued to done as the backup process completes.

apiVersion: anynines.com/v1
kind: Backup
...
status:
    ...
  managed:
    ...
    status: queued
apiVersion: anynines.com/v1
kind: Backup
...
status:
    ...
  managed:
    ...
    size: 624
    status: done

Restore a Logme2 Database Backup​

To restore a backup, you must apply a Restore from the API group anynines.com, targeting an existing Logme2 Backup. Below is the yaml file you can utilize for this purpose:

  apiVersion: anynines.com/v1
  kind: Restore
  metadata:
    name: <name>
  spec:
      backupRef: <backup-name>
      serviceInstanceType: logme2
      compositionRef:
        name: a9s-restore

And then apply the yaml manifest:

kubectl apply -f <filename.yaml>

You can observe the state transition from queued to running and done as the restore completes.

kubectl get restore.anynines.com -o yaml
apiVersion: v1
items:
- apiVersion: anynines.com/v1
  kind: Restore
  ...
  status:
      ...
    managed:
      ...
      state: queued
apiVersion: v1
items:
- apiVersion: anynines.com/v1
  kind: Restore
  ...
  status:
      ...
    managed:
      ...
      state: done

Delete a9s Kubernetes Custom Resources​

Delete the Custom Resources using the kubectl delete command. Replace <resource-type> with the actual resource type and <resource-name> with the name of the Custom Resource you want to delete.

kubectl delete <resource-type> <resource-name>

Alternatively, you can use the following command to delete Custom Resources by specifying the filename of the yaml manifest:

kubectl delete -f <filename.yaml>

Coming soon​

a9s Logme2 offers a range of features that will soon be supported for a9s Logme2 through Kubernetes integration. See the following table for a summary of these upcoming features.

FeatureDescription
MetricsMonitor, collect, and manage metrics for comprehensive insights into the service.
LoggingStream log data to a third-party service for centralized log management and analysis.
Disk Usage AlertsCreate disk usage alerts to be notified when ephemeral or persistent disk usage exceeds a certain threshold.
Database ConfigurationConfigure advanced features such as Tuning, Data Retention, TLS and Groks by defining Logme2 custom parameters.