waste not, want not

PROVERB
if you use a commodity or resource carefully and without extravagance you will never be in need.

Recently, there’s a ton of energy being spent in the Kubernetes ecosystem thinking about how to save costs. KSGate is a prototype I’ve been working on to provide a generalized and declarative solution to scheduling. One big side effect of strict scheduling is the reduction of costly resources by avoiding two aspects of Kubernetes that really tend to annoy me; wasteful scheduling and weak service dependencies.

Let me start by talking about these two things and then I’ll explain how my experiment (KSGate) plays a role in addressing them.

We’ll start with…

Wasteful Scheduling

Consider the following. Imagine we have a database and a secret the database depends on.

apiVersion: v1
kind: Pod
metadata:
  name: database
spec:
  containers:
  - name: database
    image: postgres
    envFrom:
    - secretRef:
        name: db-secret
---
apiVersion: v1
kind: Secret
metadata:
  name: db-secret
  namespace: test
data:
  POSTGRES_PASSWORD: Zm9v
type: Opaque

If you deploy the database but the secret does not exist the pod will be scheduled and the kubelet will try to get the secret. If the secret is not ready, the kubelet will mark the pod status as CreateContainerConfigError and try over and over to see if the secret ever does show up. So the resources for the pod are allocated on the node but the kubelet of the node can’t actually run it. The kubelet is spending time and resources trying to get the secret none of which is useful to your application. And who knows when the secret will be ready?

This is just one example of wasteful scheduling but I hope you get the idea that wasteful scheduling is workload scheduling that doesn’t provide any application benefit yet still incurs infrastructure costs in an uncontrolled fashion. Do you even measure how much cost is spent on compute that is not application related?

Let’s move on to…

Weak Dependencies

Now what if one resource depends on another resource and the other resource is not ready?

Consider the following. Here we have an application that depends on a database.

apiVersion: v1
kind: Pod
metadata:
  name: application
spec:
  containers:
  - name: application
    image: nginx
    env:
    - name: DB_HOST
      value: database
    - name: DB_PORT
      value: "5432"
    envFrom:
    - secretRef:
        name: db-secret

How might we model this in Kubernetes?

The first suggestion that you’re likely to come across is to use an init container (or maybe a sidecar container) to wait for the database to be ready. Something like the following:

apiVersion: v1
kind: Pod
metadata:
  name: application
spec:
  initContainers:
  - name: wait-for-database
    image: busybox
    command: ["sh", "-c", "until nc -z database 5432; do echo waiting for database; sleep 1; done"]
  containers:
  - name: application
    image: nginx
    env:
    - name: DB_HOST
      value: database
    - name: DB_PORT
      value: "5432"
    envFrom:
    - secretRef:
        name: db-secret

While functional this approach is inefficient and wasteful because the application pod is scheduled and consuming resources even though it can’t actually do something meaningful until the database is ready and there is no way to express this dependency in a way that the scheduler will respect it.

That’s why I refer to this as a weak dependency.

Either way…

Why should we care?

The two cases above have to be accepted as known wastes of resources. We know it will happen, but we can’t really do anything about it. However, factored across the entire architecture this could amount to a significant cost.

Until recently, however, there were no better options. The scheduler is allocating resources for essentially useless processes that are consuming resources and executing logic which is not part of our application.

This means that we’re not using our resources efficiently and as cloud resources increase in price this wastefulness saps the value from our infrastructure.

Enter…

Scheduling Gates

Luckily the Kubernetes maintainers have thought about this and have put hooks in place around the scheduler which allow us to control the scheduling of workloads until some set of conditions are met. This mechanism is called scheduling gates or more precisely Pod Scheduling Readiness. It reached stable status in Kubernetes 1.30.

Today, we can create a scheduling gate for the database in the first scenario that indicates the need for the secret and then wait for the gate to be removed before the database will be scheduled with zero application resources wasted.

apiVersion: v1
kind: Pod
metadata:
  name: database
spec:
  containers:
  - name: database
    image: postgres
    envFrom:
    - secretRef:
        name: db-secret
  schedulingGates:
  - name: my.scheduling.gate/db-secret

Since the scheduler won’t schedule the database pod until the gate is removed no resources are wasted. There is no logic executing, no resources are even allocated let alone consumed, and this state can be maintained indefinitely at essentially zero cost.

Similarly, we can create a scheduling gate for the application that indicates the need for the database and again wait for the gate to be removed before the application will be scheduled.

apiVersion: v1
kind: Pod
metadata:
  name: application
spec:
  containers:
  - name: application
    image: nginx
    env:
    - name: DB_HOST
      value: database
    - name: DB_PORT
      value: "5432"
    envFrom:
    - secretRef:
        name: db-secret
  schedulingGates:
  - name: my.scheduling.gate/db-secret
  - name: my.scheduling.gate/database

But Who’s the Gatekeeper?

The above approach is a good start, but it has a few drawbacks. You’ll note that I emphasized the phrase “wait for the gate to be removed”. That harkens to the fact that no one currently recognizes the scheduling gate I used so I need to write a custom controller that recognizes and knows under what conditions to remove it. As I add more and more gates I need more controllers or more code to recognize the conditions implied by each gate. This sounds like a lot of work, maybe more work than what we had before.

Declarative Scheduling Gates

What if we could define a scheduling gate in a declarative way? What if there was a scheduling gate controller that could manage the scheduling gate for us, or even better, a scheduling gate controller that could manage the scheduling gate for us and allowed us to define the conditions under which the gate should be removed in a flexible way?

That sounds pretty interesting doesn’t it?

Let’s start by considering the constraints.

First thing to consider is that scheduling gates are just opaque strings with a maximum length of 63 characters and the characters allowed are limited to alphanumeric, /, -, and _. This means that we can’t really use them for anything other than unique identifiers.

On the other hand the constraints we want to declare are details that are closely tied to the definition of the workload so it shouldn’t be kept far away from it or there’s a risk of it getting out of sync. But we can’t store that information in the scheduling gate so we need some other way to store it. It would be nice if we could avoid having to create a custom storage layer or a new CRD and force everyone to have to adapt to this new mechanism. That would make a generalized solution that no-one would adopt because it doesn’t integrate into existing resource definitions (like Helm charts and such.)

If only there was a way to store arbitrary information in the workload definition itself that could be tied to the scheduling gate identifier without the hassle of new storage layer or new CRD.

Annotations to the Rescue

As it turns out, there is a way to do this. We could use the metadata.annotations on the workload to store the condition information and bind it to the scheduling gate identifier.

apiVersion: v1
kind: Pod
metadata:
  name: application
  annotations:
    my.scheduling.gate/db-secret: "...condition..."
    my.scheduling.gate/database: "...condition..."
spec:
  containers:
  - name: application
    image: nginx
    env:
    - name: DB_HOST
      value: database
    - name: DB_PORT
      value: "5432"
    envFrom:
    - secretRef:
        name: db-secret
  schedulingGates:
  - name: my.scheduling.gate/db-secret
  - name: my.scheduling.gate/database

This approach of pairing a scheduling gate with a matching annotation, along with a little bit of semantic-fu would allow us to declare conditions directly in the definition that a generic controller could use to determine when the workload is ready to be scheduled and do it in a way that is fully compatible with existing workload definitions.

KSGate

I’ve modelled this idea and I’m working on a controller that will manage the scheduling gate and annotation pairs for us. I’ve called this controller KSGate (derived from Kubernetes Scheduling Gates).

In order to avoid conflicts with any pre-existing scheduling gates out in the wild, KSGate is designed to only consider gates that are prefixed with k8s.ksgate.org/. The suffix that must follow is arbitrary and is used by developers to uniquely identify managed gates on the workload (that gives 46 remaining characters to work with, but considering the scope of uniqueness is constrained to the resource itself that should leave plenty of room to work with).

Conditions

Here’s an example of a condition that defines a dependency on the existence of a secret named db-secret:

{
  "apiVersion": "v1", // (optional) defaults to "v1", as in core/v1
  "kind": "Secret", // required
  "name": "db-secret", // required
  "namespace": "default", // (optional) defaults to the resources's namespace
}

Conditions specify the apiVersion, kind, and name to identify the resource that the condition is referencing. The namespace property is used to specify the namespace of the resource. When omitted, the pod’s namespace is used. To target cluster scoped resources specify the "namespaced": false property.

The schema for the annotation value of a condition can be found here.

How Conditions Work

The KSGate controller identifies any workloads that are schedulingGated and identifies any matching gates. For each matching gate found a watcher is created that will receive any events for the referenced resource and when the condition is met the gate is removed.

Expressions

Expressions are what give real power to conditions.

The expression property on a condition is used to specify a CEL expression that must evaluate to true for the condition to be satisfied.

Here’s an example of a condition that uses an expression to define a dependency on the Pod named database being in the Running phase:

{
  "apiVersion": "v1", // (optional) defaults to "v1", as in core/v1
  "kind": "Pod", // required
  "name": "database", // required
  "namespace": "default", // (optional) defaults to the resources's namespace
  "expression": "resource.status.phase == 'Running'" // (optional) if omitted, the existence of the resource is used to satisfy the condition
}

The CEL environment contains two variables; resource and this:

• resource - gives access to the resource matched by the apiVersion, kind, and name properties
• this - gives access to the pod that is being scheduled.

A single function also extends the standard set of functions:

• now() - gives access to the current time so temporal expressions can be used. (e.g. (now() - timestamp(resource.metadata.creationTimestamp)) > duration('10s') means that the resources was created at least 10 seconds before now)

CEL expressions allow for complex conditions to be specified over the entire content of the pod (using this) and the target resource.

Example

Let’s see our original example with KSGate. You’ll recall that we had a database workload and a secret that the database workload depended on.

apiVersion: v1
kind: Pod
metadata:
  name: database
  annotations:
    k8s.ksgate.org/db-secret: |
      {
        "kind": "Secret",
        "name": "db-secret"
      }
spec:
  containers:
  - name: database
    image: postgres
    envFrom:
    - secretRef:
        name: db-secret
  schedulingGates:
  - name: k8s.ksgate.org/db-secret

Now the database pod has a scheduling gate for the secret and it won’t be scheduled until the secret exists, perhaps indefinitely and without any resource waste but will immediately be scheduled when the secret arrives.

Suppose we include the application such that it depends both on the secret and the database.

apiVersion: v1
kind: Pod
metadata:
  name: application
  annotations:
    k8s.ksgate.org/db-pod: |
      {
        "kind": "Pod",
        "name": "database",
        "expression": "resource.status.phase == 'Running'"
      }
    k8s.ksgate.org/db-secret: |
      {
        "kind": "Secret",
        "name": "db-secret"
      }
spec:
  containers:
  - name: application
    image: nginx
    env:
    - name: DB_HOST
      value: database
    - name: DB_PORT
      value: "5432"
    envFrom:
    - secretRef:
        name: db-secret
  schedulingGates:
  - name: k8s.ksgate.org/database
  - name: k8s.ksgate.org/db-secret

Pretty neat, right?

Closing thoughts

KSGate is a controller that enables you to define scheduling gates and the conditions under which they should be removed in a declarative way using powerful CEL expressions. In doing so it allows you to define scalable, indefinite, resource free and failure free dependencies. It can also reduce those wasteful scheduling scenarios and hopefully reduce costs.

I’m excited to see where this goes and I’m looking forward to seeing what other people think about this idea. To that end, I’ve enabled GitHub Discussions for the project where you can give feedback and share your thoughts and ideas. If you’re interested in contributing to the project, please feel free to reach out to me there.

KSGate is licensed under the permissible Apache License 2.0.

If you care to leave feedback, please do so on LinkedIn.

First the tools you need to install:

• Docker
• k3d
• kubectl

Now here’s the magic one-liner:

k3d cluster create mycluster -p 80:80@loadbalancer

Ok, that looks fairly innocent.

“What is the advantage of this over other options?” You ask.

Well, there are a couple of secrets at work here that took me a while to put together.

But let’s talk first about one of the biggest pains with doing any kind of microservices development locally; hostname resolution.

Local Hostname Resolution

Most of the time when you have any number of microservices beyond 2 (and even 2) you need to resolve hostnames. IP addresses are hard to remember and unique port numbers are a pain.

More importantly you can quickly loose affinity towards the networking aspects of production particularly necessary when working with web applications such as CORS or Content Security Policies, authorization server front channel and back channel flows, and other things that are a pain or impossible with localhost. Particularly you’d like to actually test those concerns out locally if possible.

What most people do is modify the hosts file on their local system. But this requires root or admin access. The problem with this is that it ranges from impossible on some locked down systems to just a huge pain.

Secret #1: Docker Hostname Resolution

Docker (at least on Linux and MacOS) has a solution for this in that it automatically resolves any hostname with the suffix .docker.localhost to the IP address of the Docker host.

So, for example, if you have a service running on your local system on port 8080 and you want to access it using http://myservice.docker.localhost:8080, it will work.

The ability to use an arbitrary number of hostnames without any fuss is really useful.

Secret #2: k3d Load Balancer & Port Forwarding Port 80

Our K3d command causes K3D to set up a Load Balancer (traefik) service running in a docker bridge network created for your cluster. It then sets up port forwarding from your local system’s port 80 to that Load Balancer service.

Now the really nice part is that it can actually forward port 80 which normally is a privilege that requires root or admin access. Luckily the Docker infrastructure enables this without any fuss. This means we can work with standard HTTP ports and not have to worry about unique port numbers messing up our configurations.

(Note: If you want enable HTTPS it’s a little more complicated, not much, but to get the networking setup all you’d need to add is -P 443:443@loadbalancer to our one-liner.)

The built in Load Balancer service allows you create Kubernetes Ingress resources the way you would in a production Kubernetes cluster.

For example, if you have a Kubernetes service running on port 80 and you create an Ingress resource with hostname myservice.docker.localhost and you want to access it using http://myservice.docker.localhost (note I omitted the port) it will work!

Want to test? Let’s Go!

# Create our cluster
k3d cluster create mycluster -p 80:80@loadbalancer

# Create a deployment
kubectl create deployment nginx --image=nginx

# Expose the deployment through a service
kubectl expose deployment nginx --port=80 --type=ClusterIP --name=nginx-service

# Create an ingress resource with a hostname that routes to the service
kubectl create ingress nginx-ingress --rule="myservice.docker.localhost/*=nginx-service:80"

Now you can access your service at http://myservice.docker.localhost

Test Helm with Ingress

Let’s install Keycloak using Helm and make it accessible at http://keycloak.docker.localhost

# Create our cluster
k3d cluster create mycluster -p 80:80@loadbalancer

# Add the Helm repository
helm repo add bitnami https://charts.bitnami.com/bitnami

# Install the Keycloak chart
helm install keycloak bitnami/keycloak --set ingress.enabled=true --set ingress.hostname=keycloak.docker.localhost --set auth.adminPassword=admin

Now you can access keycloak at http://keycloak.docker.localhost

Easy peasy!

If you care to leave feedback, or if you know of an even easier one liner that gives you this much functionality, please do so on LinkedIn.

Thanks for stopping by!

I was going to dive right into technical details, but I think it’s important to understand the why behind the what so I want to start with a brief overview of my recent journey.

The bulk of my career has been spent in Java. My beloved language where I spent the first 15 years of my career honing my skills every day; to this day is still a comfort zone for me.

I’ve been using it since the early 2000s where it was the main language for the curriculum at my university and while I’ve loved taking side roads into other languages and technologies, I’ve always come back to Java.

What I enjoyed so much about Java was, and is, the vastness of the ecosystem. The JVM is a powerful runtime that allows me to build performant applications. And the landscape of tools and libraries is so vast and prolific that I could always find something to help me build the right thing. The development experience was second to none for so long. Few language ecosystems could boast such a productive set of tools and features that allowed huge teams to collaborate on the same codebase. Starting from IDEs, build tools, testing frameworks, debugging tools, analytics tools, and so much more, the ecosystem is mature and full of options.

It’s even hard to believe a day would come where I would opt for anything else… and yet here we are. But I have to admit the choice was kind of made for me in a sense.

Over the course of 2 decades I worked mostly in Java on a web centric enterprise application. A monolithic application with millions of lines of code, an engineering team well in the hundreds, having countless features and integrations.

These days however, I’ve been working on “Cloud Native” applications; applications that are built to run in infrastructure that is not under my control. Bare metal barely exists today and even where it does its use is almost exclusively buried deep under layers of abstraction. Even on my local machine I’m using Docker or Kubernetes (likely both) to run my applications.

I’m working a lot with Kubernetes. And, it just so happens that the defacto language for the Kubernetes ecosystem is Go; and the most interesting work being done in the Kubernetes ecosystem is being done in Go.

The Go ecosystem is already very mature and the tooling is very good. What I like very much about Go is the simplicity of the developer experience. You immediately have opinionated tooling for building, testing, packaging and running your application. The cross compilation story is so easy that I don’t even think about it. Dependency management is just as easy and assembling an application from multiple packages is a breeze. I can easily debug both directly and remotely launched applications. I can write powerful tests, I can execute them in seconds and I can effortlessly verify code coverage. I can write complex applications and build them into a statically linked binary of only a few megabytes or I can package that binary into a container of only a few megabytes (most of the applications I’ve worked on have resulted in images of less than 15Mb).

All of this I can do within a matter of minutes after I’ve run go mod init my/app on a new project.

The language itself is simple enough for my brain to process quickly. And since I’m not enough of a language lawyer to care about the language features too much, I can focus on building my application. I’ve gotten used to the error handling and the concurrency model and honestly I rather like them. I am by no means a Go expert, but I’ve been able to pick it up quickly and apply it to build some really cool stuff. Of note are the HTTP server primitives in the standard library which are so good that I’m doing complex things in a matter of minutes.

Go is great both for building system tools and for building web applications and since those two places are where I live, I’m happy.

If you care to leave feedback, please do so on LinkedIn.

Again, I hope to write more about what I’ve been doing and what I’ve learned in the coming weeks.

Thanks for stopping by!

Many years before Cloud environments existed OSGi technology was being leveraged to deploy complex, distributed applications to countless devices. Due in large part to its resilience and innovative design it continues to be used in this fashion today. Relatively early in OSGi’s long history the Configuration Admin Service Specification was defined with much the same concerns for configuration as are present in current environments like today’s Cloud.

Kubernetes is a very popular and widely adopted technology for orchestrating applications in the Cloud and is provided by a growing number of the largest Cloud vendors. It also defines a set of core components that are responsible for keeping applications well fed with configuration.

Notably, Kubernetes configuration principles very closely resemble those of OSGi Configuration making integration quite natural which is the topic of this post.

Defining ConfigMaps

The first Kubernetes configuration component is called ConfigMap and represents the basic building block for providing non-confidential data in key-value pairs.

(Don’t place secure or data that requires encryption in ConfigMaps. Another Kubernetes component we’re going to talk about later is intended for that.)

A ConfigMap is defined in a Kubernetes manifest file (commonly using the YAML syntax) like the following:

apiVersion: v1
kind: ConfigMap
metadata:
  name: osgi-demo-config
data:
  # property-like keys; each key maps to a simple value
  pool_initial_size: "3"
  pool_max_size: "10"

  # file-like keys
  message.processor-email.config: |
    pool.initial.size=i"${env:pool_initial_size}"
	pool.max.size=i"${env:pool_max_size}"
    topic="/email"
  message.processor-log.config: |
    pool.initial.size=i"${env:pool_initial_size}"
	pool.max.size=i"20"
    topic="/log"

(We’ll be seeing a lot of YAML in this and future posts so take heart.)

The example above demonstrates the basic model for ConfigMaps. The first 4 lines are boiler plate and are setup for the data field which holds a series of key-value pairs in one of two flavours;

• property-like keys - typical key mapping to a single value
• file like keys - maps a key (typically with a file-like name) to a multi-line chunk of data (that looks a lot like a file)

Take note of the syntax used in the file content. We’ll come back to that later.

The next thing you should note about the value of the file-like-keys flavour is that the format of the value is largely irrelevant. The ConfigMap does not care one way or the other if it’s XML, JSON, Java properties files, more YAML, or any other character based syntax you wish (I supposed it could even be script… but I’d be careful with that). The only real restriction is that a given ConfigMap’s data does not exceed 1 MiB in size.

Consuming ConfigMaps

There are several ways this could be used but we’ll talk about the 2 most common.

Consider the following Pod spec.

apiVersion: v1
kind: Pod
metadata:
  name: osgi-demo-pod
spec:
  containers:
    - name: osgi-demo-container
      image: rotty3000/config-osgi-k8s-demo
      env:
        # Define environment variables
        - name: pool_initial_size
          valueFrom:
            configMapKeyRef:
              name: osgi-demo-config # The ConfigMap this value comes from
              key: pool_initial_size # The key to fetch
        - name: pool_max_size
          valueFrom:
            configMapKeyRef:
              name: osgi-demo-config
              key: pool_max_size
      volumeMounts:
      - name: config
        mountPath: "/app/configs"
        readOnly: true
  volumes:
    - name: config
      configMap:
        # The name of the ConfigMap you want to mount
        name: osgi-demo-config

(Pods are the smallest deployable units of computing in a Kubernetes cluster.)

The example above defines a Pod, the first 5 lines of which are pretty boiler plate, named osgi-demo-pod, has exactly one container named osgi-demo-container. The container specifies the Docker image to be rotty3000/config-osgi-k8s-demo. That alone is the basic information necessary to define a usable Pod. You could deploy this and have a running system:

apiVersion: v1
kind: Pod
metadata:
  name: osgi-demo-pod
spec:
  containers:
    - name: osgi-demo-container
      image: rotty3000/config-osgi-k8s-demo

(Though Naked Pods are discouraged, they are useful for illustration.)

However, this is not sufficient in the majority of cases. Usually some additional input is required, such as resource constraints, volume mounts, configuration, etc.

Let’s start our examination at the bottom of the spec with the volumes field. Volumes are Kubernetes’ mechanism for sharing file systems that supplement a Pod’s own ephemeral file system (ephemeral meaning nothing that is modified in the Pod’s own file system is retained across Pod restarts). There are many different types of Volumes in Kubernetes. The one we’re showing here adds a ConfigMap:

  volumes:
    - name: config
      configMap:
        # The name of the ConfigMap you want to mount
        name: osgi-demo-config

In order for the ConfigMap to be usable it must be mounted as a volume, so we define the volume by first giving it a name (config), by specifying a Volume type in this case a configMap named (osgi-demo-config).

(The Pod and the ConfigMap have to be in the same Namespace.)

Now that the volume is defined we can mount it into the pod using the volumeMounts field under the containers array:

      volumeMounts:
      - name: config
        mountPath: "/app/configs"
        readOnly: true

The mount is set to be located at /app/configs. In this case the image we’re using already listens to this directory using Apache Felix FileInstall; an OSGi bundle that manages OSGi configurations from the file system on demand. A perfect companion for Kubernetes ConfigMaps. FileInstall is configured to do this using the system property felix.fileinstall.dir=/app/configs.

Mounted files

You should note that as configured the volume will cause each key in the ConfigMap to be mounted as a separate file in the mount directory (the value of each pair being the contents of the file). This is great because FileInstall automatically detects and manages files that end with .config (or the older .cfg) identified in it’s scanned directory . (Unknown files will be ignored.)

Mounting specific entries

You can pick and choose which keys of the ConfigMap are loaded as files by adding an items array:

  volumes:
    - name: config
      configMap:
        # The name of the ConfigMap you want to mount
        name: osgi-demo-config
        # An array of keys from the ConfigMap to create as files
        items:
        - key: "message.processor-email.config"
          path: "message.processor-email.config"
        - key: "message.processor-log.config"
          path: "message.processor-log.config"

However; I don’t recommend the items approach in the OSGi Configuration scenario in the default case because it forces a duplication of the same information in two places; the ConfigMap and the volumes definition. I suggest lettings the ConfigMap be the source of truth and I’ll explain why a little later.

Sub-directory scans

By default FileInstall scans sub-directories as well, so create any hierarchy that suites your needs by mounting the ConfigMap in any sub-directory of the path scanned by FileInstall. This is handy for grouping related configuration files.

Environment Variables

Another way to use the key-value pairs of the ConfigMap in the Pod is by defining environment variables. If you go back to the env field of the Pod spec you’ll see the following:

      env:
        # Define environment variables
        - name: pool_initial_size
          valueFrom:
            configMapKeyRef:
              name: osgi-demo-config # The ConfigMap this value comes from
              key: pool_initial_size # The key to use
        - name: pool_max_size
          valueFrom:
            configMapKeyRef:
              name: osgi-demo-config
              key: pool_max_size

Here, two of the keys are cherry-picked from the ConfigMap and turned into environment variables that will be available in the Pod from the moment of startup.

Interestingly, if you recall the note about the syntax of the configuration files content which I’ve replicated next,

  message.processor-email.config: |
    pool.initial.size=i"${env:pool_initial_size}"
	pool.max.size=i"${env:pool_max_size}"
    topic="/email"

you should be aware that FileInstall has built in interpolation for environment variables using the env: prefix. This allows you to compose configuration using the environment with no additional tooling installed.

Advanced interpolation using mounted files

Remember those property-like keys we discussed earlier? As was just stated a ConfigMap volume will cause these to be mounted as individual files. FileInstall will gladly ignore them, however it could be interesting, particularly if the contents of the directory comes from different ConfigMaps, to have a more advanced interpolation mechanism that would allow those to be used as a source of values.

As it turns out the Apache Felix project provides a companion bundle that adds exactly this functionality via a Configuration Plugin. This bundle is called org.apache.felix.configadmin.plugin.interpolation and it’s already part of the base image we’re using in the examples.

We configure the Felix interpolation plugin using system properties.

The first property tells Felix Config Admin (the implementation of OSGi Configuration Admin) to require the plugin before processing any configuration:

felix.cm.config.plugins=org.apache.felix.configadmin.plugin.interpolation

This second property tells the plugin which directory to search for values:

org.apache.felix.configadmin.plugin.interpolation.secretsdir=/app/configs

With that in mind, consider the 2 following data sections from 2 separate ConfigMaps:

## ConfigMap #1
# assume this is mounted as `/app/configs/values`
data:
  player_initial_lives: "3"

## ConfigMap #2
# assume this is mounted as `/app/configs/files`
data:
  game.pid.config: |
    player.initial.lives="$[secret:values/player_initial_lives;type=long]"
    player.maximum.lives=i"5"
    colors="$[secret:colors;type=String[];delimiter=|;default=green|red|blue]"

As you can see with the syntax provided by the Felix interpolation plugin allows us to refer to ConfigMap files as interpolation values.

You’ll also note that Felix interpolation plugin has more advanced capabilities like rich type coercion and the ability to provide defaults for missing values.

Dynamic reaction to configuration changes

Many software systems are capable of gracefully handling changes in configuration without requiring full restarts. For example Apache HTTPD Server can use it’s graceful restart mode to smoothly reload it’s configuration and automatically adjust its behaviour accordingly. NGINX offers a similar functionality and so do many other systems.

Besides the obvious goal of reducing service interruptions this also supports the notion of feature flags, service discovery and other real-time signals required to efficiently and speedily control system behaviour.

ConfigMaps as mounted files vs. environment variables

Given that mounted ConfigMaps are updated automatically without needing to restart the Pod vs. environment variable which require a Pod be restarted in order to be updated means that mounted files are more efficient for systems that are designed to be signalled on configuration file changes.

Conclusion

OSGi Configuration Admin is meant to dynamically propagate configuration changes throughout an OSGi framework. Apache Felix FileInstall adds to that the ability to react to changes in configuration resources on the file system which are subsequently propagated to Configuration Admin. Kubernetes ConfigMaps provide Pods with centrally and dynamically updated configuration resources.

The combination of the three makes for a completely dynamic and fully integrated application configuration system with very little effort.

In a future post I plan to further various aspects of this subject. So stay tuned!

Test Resources

The project demonstrating the ideas in this post can be found in this repository. The docker image that defines the configurable OSGi application can be found here on Docker Hub.

Recently however, the degree to which I’ve had to immerse myself has lead to more understanding. With that in mind, this article is for JavaScript beginners, like myself, trying to be productive on the outer rim of the JavaScript universe.

Today’s challenge starts with Liferay Workspace but what I should start by clarifying is that I am not talking about a Liferay NPM Bundler type of build, nor one that produces output intended to integrate (per say) with the Liferay JavaScript Module Loaders. Those procedures result in output that is proprietary to Liferay and therefore cannot work with pure JavaScript consumers (such as you’d expect to find within things like third party web components or SPAs of various types.) So the idea here is to produce JavaScript output that is not proprietary to Liferay.

Secondly, I should clarify that I am not suggesting that Liferay’s JavaScript tooling is unnecessary. The tooling is both needed and great at addressing many concerns that need to be taken into consideration when participating in an ecosystem of a vast product like Liferay DXP. However, sometimes you just have other constraints. That’s the perspective that is driving this discussion.

So, with all that out of the way, let’s get started with a basic Liferay Workspace project setup.

You can follow along by looking at the adding-javascript-build branch of my workspace Github project. In this procedure I’m going to start with a new workspace to outline all the steps to get started.

The workspace

Make sure that you’ve got blade cli installed.

Create (init) a new workspace by executing:

blade init -v portal-7.2-ga2 <name of workspace>

(You can see a list of the most recent versions of every Liferay Portal product available by executing blade init -l. And if you need an exhaustive list you can use blade init -l --all)

Once the workspace is created I always recommend verifying the very latest version of the workspace plugin is specified in the settings.gradle file in the workspace root. To find the latest version of the workspace plugin look here.

At the time of this writing the change to update my workspace plugin looked like this:

 buildscript {
 	dependencies {
-		classpath group: "com.liferay", name: "com.liferay.gradle.plugins.workspace", version: "3.4.2"
+		classpath group: "com.liferay", name: "com.liferay.gradle.plugins.workspace", version: "3.4.5"
 		classpath group: "net.saliman", name: "gradle-properties-plugin", version: "1.4.6"
 	} 

Next let’s test that the workspace is properly configured by executing

./gradlew initBundle

Sure there are no modules to speak of but performing this action downloads the workspace specified version of gradle, if not already downloaded, it retrieves all the dependencies for a slew of default plugins with which the Liferay Workspace come pre-configured and finally it downloads the bundle of the Liferay version specified.

With the Liferay bundle initialised and assuming you’ve not changed any other workspace settings (in gradle.properties) it should now be possible to start a running instance of Liferay portal by executing the command:

bundles/tomcat-${tomcat_version}/bin/catalina.sh run

(You can determine the tomcat version just by looking in the bundles directory. I usually use tab completion to auto-complete paths to save time.)

This command starts Tomcat (and Liferay) in the foreground with logs outputted to stdout. You can stop Tomcat and Liferay with ctrl-D.

Now personally, I invariably end up writing code that needs to be debugged. This means I end up needing to run Liferay portal in debug mode. Thankfully this is trivial with Tomcat’s built in debug launch mode. Just add jpda to the command above before the run argument. The full command ends up being

bundles/tomcat-${tomcat_version}/bin/catalina.sh jpda run

and Tomcat starts up with remote debugging enabled on port 8000.

One nice thing about the Liferay portal bundle is that without any other configuration it will run locally with the embedded HyperSQL database and Elasticsearch search engine to make it easy to get underway.

The module

Now let’s start a new module. Start by moving into the modules directory of the workspace and then execute the following:

blade create -t service -s java.util.function.Supplier adding-javascript-build

This is a simple service type project with a class that implements java.util.function.Supplier to be published as an OSGi service. This module is inane but demonstrative enough to get us going. We’re not focusing on the OSGi part specifically at this time but we’re setting out to prove that while we have an OSGi module we’re also going to get some JavaScript goodness too.

The generated class

Let’s take a moment to touch on the class that was generated as part of the module creation. It looks like this (with comments removed):

package adding.javascript.build;
import java.util.function.Supplier;
import org.osgi.service.component.annotations.Component;
@Component(
	immediate = true,
	property = {
	},
	service = Supplier.class
)
public class AddingJavascriptBuild implements Supplier {
}

The first thing you probably noticed is that it doesn’t even compile. This is because the template didn’t fill out any required methods for the service type we picked. Let’s fix that, and also let’s add the generic type while we’re at it, make it return something interesting, make it a gogo command and finally we’ll add some (de)activate output so we can see what’s happening as we (re)deploy the module:

@@ -1,11 +1,27 @@
 package adding.javascript.build;
 import java.util.function.Supplier;
+import org.osgi.service.component.annotations.Activate;
 import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Deactivate;
 @Component(
 	immediate = true,
 	property = {
+		"osgi.command.scope=ajb",
+		"osgi.command.function=get"
 	},
 	service = Supplier.class
 )
 public class AddingJavascriptBuild implements Supplier<String> {
+	@Override
+	public String get() {
+		return "Something interesting!";
+	}
+	@Activate
+	void activate() {
+		System.out.println("Activated!");
+	}
+	@Deactivate
+	void deactivate() {
+		System.out.println("Deactivated!");
+	}
 }

Once we’ve built and deployed this module we should be able to telnet into Liferay’s embedded Gogo shell by executing telnet localhost 11311. Once there execute the ajb:get command. You should see the output of our supplier service:

]$ telnet localhost 11311
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
____________________________
Welcome to Apache Felix Gogo

g! ajb:get
Something interesting!
g! 

Enable WAB

Next, we’re going to enable the module as a skinny WAB (Web Application Bundle). In Liferay parlance a skinny WAB is a web application that is shaped like a JAR instead of like a WAR and the only thing we need is to edit the bnd.bnd file that is in the root of the module and add the header Web-ContextPath like so:

 Bundle-Name: adding-javascript-build
 Bundle-SymbolicName: adding.javascript.build
 Bundle-Version: 1.0.0
+
+Web-ContextPath: /adding-javascript-build

The value of the header should contain a context path unique for our application.

The reason for turning our module into a WAB is so that we can serve resources. This will be essential later when we have some JavaScript to serve.

Vanilla JavaScript

Now, if all we needed was some vanilla JavaScript code then we’d only need to place the files within the src/main/resources/META-INF/resources/ directory of our module and that would be sufficient. The files would automatically be accessible from <hostname>/o/adding-javascript-build/... due to our module being a WAB. The /o is the path withing Liferay used to target OSGi modules and is added to any WAB paths. In a skinny WAB all resources under the path src/main/resources/META-INF/resources/ (in the built JAR this translates to /META-INF/resources) are mapped to a default Servlet that serves them up using an appropriate mime type. Sweet right?

Advanced JavaScript

Assuming that we’re using more than vanilla JavaScript what we’ll do is initialise a JavaScript build by performing:

npm init -y

This gives us a simple package.json file to start with in the root of our module directory.

Next let’s create the file src/main/resources/META-INF/resources/js/index.ts. The .ts extension stands for TypeScript which is a popular way these days of developing JavaScript in a type safe way (go figure ;) ). Let’s start simple:

const user = {
  firstName: "Rotty",
  lastName: "3000",
  role: "Programmer guy"
};

console.log("User: %O", user);

export {};

Right, so now we have a source file, and we have the basic package.json but we still can’t build because we don’t have a builder. If we tried to run the workspace build right now it would not be happy.

However, you should notice that Liferay Workspace recognises the fact that there is a JavaScript build in the module and does some setup and attempts to execute some npm tasks. However it errors out with something along the lines of:

> Task :modules:adding-javascript-build:downloadLiferayModuleConfigGenerator

...

> core-js@2.6.12 postinstall /home/rotty/projects/com.github.rotty3000.workspace/modules/adding-javascript-build/node_modules/core-js
> node -e "try{require('./postinstall')}catch(e){}"

...

npm ERR! core-js@2.6.12 postinstall: `node -e "try{require('./postinstall')}catch(e){}"`
npm ERR! Exit status 139
npm ERR! 
npm ERR! Failed at the core-js@2.6.12 postinstall script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/rotty/.npm/_logs/2021-03-22T03_53_00_117Z-debug.log

> Task :modules:adding-javascript-build:downloadLiferayModuleConfigGenerator FAILED

...

BUILD FAILED in 31s
4 actionable tasks: 4 executed

Don’t even bother trying to make sense of this, it’s really just a long winded way of saying

I really have no idea what’s going on… Please help!!!

Liferay Workspace is trying to use it’s built in NPM builder plugin configuration but is failing to find what it thinks are critical pieces of information to tell it what to do. To get around this we need to add a build script defined in package.json that will perform an action of our choosing. Let’s start with something very trivial:

@@ -4,7 +4,8 @@
 	"description": "",
 	"main": "index.js",
 	"scripts": {
-		"test": "echo \"Error: no test specified\" && exit 1"
+		"test": "echo \"Error: no test specified\" && exit 1",
+		"build": "echo 'test, test, test'"
 	},
 	"keywords": [],
 	"author": "",

If you rebuild now you should see that Liferay Workspace accepted that we’re taking over and ran our simple build script. This means we’re now in control. Great!

Since we’re creating a Liferay module we surely never intend to publish this project to an NPM repository so we should declare the package private and we also don’t need an entry point per say so let’s make both edits next:

@@ -2,7 +2,7 @@
 	"name": "adding-javascript-build",
 	"version": "1.0.0",
 	"description": "",
-	"main": "index.js",
+	"private": true,
 	"scripts": {
 		"test": "echo \"Error: no test specified\" && exit 1",
 		"build": "echo 'test, test, test'"

NPM/Node Version

When working with the most recent tooling we often run into limitations if using older versions of NPM and/or Node. Liferay’s conservative defaults are a little too dated to work with the state of the art in JavaScript. Let’s boost that up but not too high. We want to ensure the best compatibility in case the workspace contains older projects. I’ve found that the sweet spot is around version 12.20.0 of Node. Most order JavaScript projects only need slight alterations to work with this version and we also are able to execute almost all the latest JavaScript tooling.

Open the build.gradle file in the root of the Liferay Workspace and add the following (if you have existing build configurations just make sure to integrate this):

allprojects {
	plugins.withId("com.liferay.node") {
		node.global = true
		node.nodeVersion = '12.21.0'
		node.npmVersion = '6.14.11'
	}
}

TypeScript

In this specific scenario we have TypeScript source files which means we need to compile them so we need the tools to handle that:

npm install typescript --save-dev

We also need to configure some details of TypeScript compilation. For this we need a configuration file called tsconfig.json. Create this file in the module directory with the following contents:

{
	"compilerOptions": {
		"allowJs": true,
		"checkJs": true,
		"module": "es6",
		"moduleResolution": "node",
		"noImplicitAny": true,
		"outDir": "./build/resources/main/META-INF/resources/",
		"rootDir": "./src/main/resources/META-INF/resources/",
		"sourceMap": true,
		"strict": true,
		"target": "es6"
	},
	"include": [
		"./src/main/resources/META-INF/resources/**/*"
	]
}

Check the documentation for the specific details of each configuration but this is approximately what is needed for our use case, where we have a Maven-ish project structure which produces a skinny WAB result so our configuration reflects that.

You can test the output by executing the TypeScript compiler command directly from the command line:

tsc

If you have any errors whether logical, or with type safety you should find out pretty quickly.

We could stop here if all we wanted was to compile our TypeScript sources into JavaScript. We could modify the build script to invoke the TypeScript compiler we’d be off to the races.

 	"private": true,
 	"scripts": {
 		"test": "echo \"Error: no test specified\" && exit 1",
-		"build": "echo 'test, test, test'"
+		"build": "tsc"
 	},
 	"keywords": [],
 	"author": "",

The resulting output of executing the gradle jar task is now:

]$ bnd print -l build/libs/adding.javascript.build-1.0.0.jar 
[LIST]
META-INF
  MANIFEST.MF
META-INF/resources
META-INF/resources <no contents>
META-INF/resources/js
  index.js
  index.js.map
  index.ts
OSGI-INF
  adding.javascript.build.AddingJavascriptBuild.xml
adding
adding <no contents>
adding/javascript
adding/javascript <no contents>
adding/javascript/build
  AddingJavascriptBuild.class

But we’re not done yet so let’s move ahead.

Webpack

.. is “a static module bundler for modern JavaScript applications.”

We want Webpack to handle the complexity of bundling (a.k.a. assembling) any dependencies we might introduce. We’ll install it by executing:

npm install webpack webpack-cli --save-dev

While Webpack can function without configuration, in our case we have loftier goals than what the basic configuration supports. So let’s start with a relatively simple webpack.config.js file. Keep in mind we also want to handle the fact that we have TypeScript:

const path = require('path');

const PUBLIC_PATH = '/o/adding-javascript-build/';

module.exports = {
	mode: 'production',
	context: path.resolve(__dirname),
	entry: './src/main/resources/META-INF/resources/js',
	module: {
		rules: [
			{
				test: /\.tsx?$/,
				use: 'ts-loader',
				exclude: /node_modules/,
			},
		],
	},
	resolve: {
		extensions: ['.tsx', '.ts', '.js'],
	},
	output: {
		filename: 'js/bundle.js',
		libraryTarget: 'window',
		path: path.resolve('./build/resources/main/META-INF/resources/'),
		publicPath: PUBLIC_PATH,
	},
};

Several key points to look at here. First thing we notice is that in order to handle the TypeScript files we use a plugin called ts-loader . We need to install that:

npm install ts-loader --save-dev

The rest of the configuration revolves around where our sources are, and where we want the output to end up. There are also places to configure details about the output module syntax and whether the result is optimised or production and so on. I recommend reading slowly through the webpack configuration documentation to learn the key concepts.

With this we can also change the build script to call Webpack, which along with the other Webpack related changes makes for the following:

@@ -5,12 +5,15 @@
 	"private": true,
 	"scripts": {
 		"test": "echo \"Error: no test specified\" && exit 1",
-		"build": "tsc"
+		"build": "webpack"
 	},
 	"keywords": [],
 	"author": "",
 	"license": "ISC",
 	"devDependencies": {
-		"typescript": "^4.2.3"
+		"ts-loader": "^8.0.18",
+		"typescript": "^4.2.3",
+		"webpack": "^5.27.2",
+		"webpack-cli": "^4.5.0"
 	}
 }

If we run our build again we should now have a jar that contains the following:

]$ bnd print -l build/libs/adding.javascript.build-1.0.0.jar 
[LIST]
META-INF
  MANIFEST.MF
META-INF/resources
META-INF/resources <no contents>
META-INF/resources/js
  bundle.js
  index.ts
OSGI-INF
  adding.javascript.build.AddingJavascriptBuild.xml
adding
adding <no contents>
adding/javascript
adding/javascript <no contents>
adding/javascript/build
  AddingJavascriptBuild.class

And finally, if we want to load our JavaScript file in the portal we can do so by adding the following in the bnd.bnd file:

 Bundle-SymbolicName: adding.javascript.build
 Bundle-Version: 1.0.0
 
+Liferay-JS-Resources-Top-Head: /js/bundle.js?ts=${tstamp}
+Liferay-Top-Head-Weight: 1000
 Web-ContextPath: /adding-javascript-build

Couple of points to mention here. First is that we added a build-time auto-generated ts parameter to the URL. That will help flush client caches whenever we redeploy a new version of our WAB. Besides that, the URL will be prefixed by the full context path of the WAB at runtime for us. This could have been achieved with file name hashing via Webpack, but for my own reasons I wanted to avoid doing that. Maybe a point for future discussion…

The second point is about the header Liferay-Top-Head-Weight. This allows us to give the file a weight among all other top head JavaScript files in the portal so you have some measure of control on ordering. In this case the larger the number the later it gets added. Values range from Integer.MIN_VALUE to Integer.MAX_VALUE.

Conclusion

The ability to add JavaScript builds in your Liferay Workspace modules is pretty essential these days. As it turns out once I waded through the mounds of information and grasped some of the concepts it turned out not to be so bad. In later posts I’ll dig into some more advanced scenarios and use cases.

Until next time.

In the meantime I had suddenly the need to make some curl requests to HTTPS endpoints AND I’m on a machine which has a corporate security proxy. Nice thing is that Git Bash also includes curl (among several other necessary commands.)

But when I tried to use it I saw errors like:

foo@bar MINGW64 ~
$ curl https://cdn.azul.com/zulu/bin/zulu11.43.55-ca-jdk11.0.9.1-win_x64.zip --output zulu11.zip
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.haxx.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

Seemed in order to get through the proxy a corporate certificate is required.

Now, at that moment I could not invoke admin rights to place the certificate into the Git Bash mingw install directory as instructed, so how to proceed?

You’ll notice that later in the documentation it describes that curl has a environment variable CURL_CA_BUNDLE that does not require admin rights to modification of the file system.

Edit your ~/.bashrc file and add the following:

export CURL_CA_BUNDLE="/c/foo/corp-cert.crt"

With that curl commands should start the work.

• cm:createfactoryconfiguration - create a factory configuration (maps to the Configuration Admin method createFactoryConfiguration(String) or createFactoryConfiguration(String,String))
• cm:getconfiguration - create a single configuration (maps to the Configuration Admin method getConfiguration(String) or getConfiguration(String,String))
• cm:getfactoryconfiguration - get or create a factory configuration (maps to the Configuration Admin method getFactoryConfiguration(String,String) or getFactoryConfiguration(String,String,String))
• cm:listconfigurations - list configurations (maps to the Configuration Admin method listConfigurations(String))

Note: You may find that when using help the commands come up in camel case. Luckily commands are case insensitive so you can use all lower case to simplify execution if you choose.

listconfigurations

The most useful function right off the bat is to list any existing configurations that might already exist in the framework using the listconfigurations:

g! listconfigurations "(service.pid=*)"
Configuration PID=foo.bar, factoryPID=null, bundleLocation=?
Configuration PID=foo.baz, factoryPID=null, bundleLocation=?

To get all configurations:

g! listconfigurations null
...
Configuration PID=foo.bar, factoryPID=null, bundleLocation=?
Configuration PID=foo.baz, factoryPID=null, bundleLocation=?
...

To get an individual configuration from the list you can use the array syntax:

g! c = (listconfigurations "(service.pid=?)") 0
Properties           [foo=bar, service.pid=foo.bar]
Attributes           []
FactoryPid           null
Pid                  foo.bar
ChangeCount          2
BundleLocation       ?

To list the properties of a configuration in tabular form you can use:

g! $c properties
foo                 bar
service.pid         foo.bar

getconfiguration: Get or create single configurations

You can get a configuration using:

g! c = getconfiguration "foo.biz"
Properties           null
Attributes           []
FactoryPid           null
Pid                  foo.biz
ChangeCount          1
BundleLocation       reference:file:???????/org.apache.felix.gogo.runtime-1.1.4.jar

However, you’ll note that if the configuration doesn’t exist a new instance is returned. The problem is that if you use the single argument getconfiguration AND the configuration does not already exist what you will get is an instance that is only visible to the bundle that triggered the creation (notice the BundleLocation above), which is not usually what you want. In that case you should use:

g! c = getconfiguration "foo.bom" "?"
Properties           null
Attributes           []
FactoryPid           null
Pid                  foo.bom
ChangeCount          1
BundleLocation       ?

Note that now you have a BundleLocation of ? which means it is visible to any bundles that want to read it.

If you don’t want the or create behaviour it’s best to use listconfigurations when searching for configurations (it’s more powerful anyway since you can filter on any properties of the configurations).

Configuration Plugins & Processed Properties

If you happen to have a Configuration Admin that implements the 1.6 version of the spec you might also have Configuration Plugins that are able to alter or interpolate configurations (e.g. Felix ConfigAdmin Interpolation Plugin.)

Suppose you have this FileInstall config called game.pid.config which uses Felix Interpolation Plugin interpolation:

player.initial.lives="$[env:player_initial_lives]"
player.maximum-lives="5"

You’d want to call the getProcessedProperties method of Configuration to cause plugins to execute over the properties. This method does have one argument, a ServiceReference to a service that can contextualize the processing (i.e. to find properties/files for instance.)

In the case of the Felix Interpolation Plugin all you need is a ServiceReference to the ConfigurationAdmin service itself:

g! sr = servicereference org.osgi.service.cm.ConfigurationAdmin

With that you can call the getProcessedProperties method to see the properties fully resolved:

g! (getconfiguration "game.pid") processedproperties $sr
player.initial.lives 3
player.maximum-lives 5

Create configurations from scratch

So let’s say that no configuration exist for the PID and you also want to configure it with properties. First you need a way to create a Dictionary object since that is the argument required by the Configuration.update(Dictionary) method.

You can use the following to create a dictionary object:

g! d = (((bundle 0) loadclass java.util.Hashtable) newInstance)

Add some properties:

g! $d put "Foo" "bar"

Print the result:

g! $d
Foo                 bar

Now you can pass this dictionary to the configuration you have stored in the var c:

g! $c update $d
g! $c
Properties           [Foo=bar, service.pid=foo.bom]
Attributes           []
FactoryPid           null
Pid                  foo.bom
ChangeCount          2
BundleLocation       ?

createfactoryconfiguration: Create factory configurations

The basic incarnation of createfactoryconfiguration has the same gotchas as getconfiguration where it will create a configuration with a BundleLocation limited to the caller bundle. So you should prefer the two argument version as follows:

g! c = createfactoryconfiguration "foo.biz" "?"
Properties           null
Attributes           []
FactoryPid           foo.biz
Pid                  foo.biz.54bf0c1f-a7bd-4bfd-a80f-fedf58793442
ChangeCount          1
BundleLocation       ?

Notice that now the PID contains a generated part, e.g. foo.biz.54bf0c1f-a7bd-4bfd-a80f-fedf58793442.

Setting configuration properties is exactly the same as above.

getfactoryconfiguration: Named factory configurations

Recent versions of Configuration Admin specification make it possible to create named configurations. The command getfactoryconfiguration follows the pattern getConfiguration with it’s get or create paradigm. However, the difference between this and the createfactoryconfiguration is the name argument which allows passing a human readable string to uniquely disambiguate factory configurations beyond the opaque generated suffix normally used for factory configurations which make them hard to identify. Here we also prefer adding the third argument so that we make the configuration readable by any bundle.

g! c = getfactoryconfiguration "foo.biz" "one" "?"
Properties           null
Attributes           []
FactoryPid           foo.biz
Pid                  foo.biz~one
ChangeCount          1
BundleLocation       ?

Notice that in this case the PID is suffixed with a tilde (~) followed by the human readable string argument we passed (one).

What about older versions of Felix Configuration Admin

Earlier I mentioned:

if you are fortunate enough to have access to a very modern version of Apache Felix Configuration Admin you can already benefit from the fact that you can interact with Configuration Admin through the Gogo shell with the commands

Well, it turns out that even if you are using an older version you can still do most of the above provided you create a command from the Configuration Admin service (if the service is available).

First you may need to setup the command context so that you have a few basic commands:

g! addcommand context ${.context}

(This gives you access to commands like servicereference <fqcn|filter>.)

Now you can add the config admin service commands with:

g! addcommand cm (service (servicereference "org.osgi.service.cm.ConfigurationAdmin"))

That’s it! Now everything above should work exactly as documented.

The Eclipse Platform is now releasing quite frequently and this is awesome in many respects, but one side effect is that the configuration in Eclipse needed to work against the HEAD of master is constantly changing and managing this, or figuring out what is required to get things working in the IDE again can be a pain.

By far the most annoying detail is the Target Platform and specifically a couple of Orbit bundles I need for equinox http servlet. The issue is caused by the version of the Orbit drop and Platform SDK always changing for obvious reasons.

The solution however came in the form of a tutorial on vogella.com called Eclipse Target Platform.

The interesting details are about the dependency versions. Apparently in editing the .target resource you can use the placeholder version 0.0.0 to indicate using the latest.

The other interesting detail is that the 2 P2 sites I care about for this target platform both have latest aliases:

• http://download.eclipse.org/releases/latest
• https://download.eclipse.org/tools/orbit/downloads/latest-R/

I don’t know about you but I find these aliases to be notoriously hard to find.

So now I have an eclipse project in my workspace called target-platform like in the Vogella tutorial and a latest-target-platform.target file which contains:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?pde version="3.8"?>
<target name="latest-target-platform">
	<locations>
		<location includeAllPlatforms="false" includeConfigurePhase="true" includeMode="planner" includeSource="true" type="InstallableUnit">
			<repository location="http://download.eclipse.org/releases/latest"/>
			<unit id="org.eclipse.sdk.feature.group" version="0.0.0"/>
		</location>
		<location includeAllPlatforms="false" includeConfigurePhase="true" includeMode="planner" includeSource="true" type="InstallableUnit">
			<repository location="https://download.eclipse.org/tools/orbit/downloads/latest-R/"/>
			<unit id="org.apache.commons.fileupload" version="0.0.0"/>
			<unit id="org.apache.commons.fileupload.source" version="0.0.0"/>
		</location>
	</locations>
</target>

Now I hope I never have to search for the correct Orbit and Eclispe SDKs ever again.

Getting a mocked service up and running was pretty trivial thanks to some pretty good documentation. I won’t go into any details because I could never do their documentation justice in a short post. But creating a mock service with responses and some scripts was pretty simple.

Once we had a mock service built our main concern was running it in a CI environment using gradle and wrapped around the soap client test cases.

Executing the mock service standalone involves executing a command like the following:

sh SoapUI/bin/mockservicerunner.sh -s src/testIntegration/resources/soapui-settings.xml src/testIntegration/resources/soapui-project.xml

This starts a process which runs the mocked soap service until any input is sent to stdin which terminates it.

Coordinating this in gradle involves adding some actions before and after the integration tests run.

Note that we added the SoapUI binaries directly into source control so that they would be available to execute during the build.

The first thing we’re going to do is create a variable to hold the external process so that we can stop it when we’re done:

def process

In this build integration tests are defined and executed by the testIntegration task so adding an action before execution involves configuring the doFirst closure for it.

tasks.named('testIntegration') {
	doFirst {
		def cmd = "sh SoapUI/bin/mockservicerunner.sh -s src/testIntegration/resources/soapui-settings.xml src/testIntegration/resources/soapui-project.xml"

		process = cmd.execute([], project.projectDir)
		process.consumeProcessOutput(System.out, System.err)
		// give process some time to fully start
		sleep(2000)
	}
}

We used the groovy execute function and passed two parameters; the environment ([]) and the current working directory (project.projectDir) so that relative file paths would be relative to the project.

In order to see that the process is started correctly we also made sure groovy consumes all the output from the process and adds it to the gradle output using the consumeProcessOutput helper method.

We also need to shutdown the process when tests are done. So we created a stopSoapUi task with a doLast action:

tasks.register('stopSoapUI') {
	doLast {
		println('Stopping SoapUI')
		if (process != null) {
			process.withWriter {it << ' '}
			process.waitForOrKill(1000)
			process = null
		}
	}
}

In the stopSoapUI task we send a character to the stdin of the process to ask it to terminate properly, then wait for a bit to before we ultimately forcibly kill the process (whichever happens first).

Now that we have our task to stop the process we need to make sure it gets executed regardless of what errors occur either in tests or otherwise. In gradle the way to achieve this type of transactional behaviour is by using the finalizedBy function. We add a finalizedBy by to the testIntegration configuration as follows:

tasks.named('testIntegration') {
	doFirst {
		def cmd = "sh SoapUI/bin/mockservicerunner.sh -s src/testIntegration/resources/soapui-settings.xml src/testIntegration/resources/soapui-project.xml"

		process = cmd.execute([], project.projectDir)
		process.consumeProcessOutput(System.out, System.err)
		// give process some time to fully start
		sleep(2000)
	}
	finalizedBy tasks.named('stopSoapUI')
}

And there you have it! Using this approach you should be able to handle virtually any external process required for integration testing.

The full code is as follows:

def process

tasks.register('stopSoapUI') {
	doLast {
		println('Stopping SoapUI')
		if (process != null) {
			process.withWriter {it << ' '}
			process.waitForOrKill(1000)
			process = null
		}
	}
}

tasks.named('testIntegration') {
	doFirst {
		def cmd = "sh SoapUI/bin/mockservicerunner.sh -s src/testIntegration/resources/soapui-settings.xml src/testIntegration/resources/soapui-project.xml"

		process = cmd.execute([], project.projectDir)
		process.consumeProcessOutput(System.out, System.err)
		// give process some time to fully start
		sleep(2000)
	}
	finalizedBy tasks.named('stopSoapUI')
}

New Developers and SCM metadata headers:

Bundle-Developers: raymond.auge;email=raymond.auge@liferay.com;name="Raymond Augé"; organization="Liferay, Inc."
Bundle-SCM: url=https://github.com/liferay/foo,connection=scm:git:https://github.com/liferay/foo.git,developerConnection=scm:git:git@github.com:liferay/foo.git

Manifest Annotations build-time annotations designed to ease metadata maintenance

• Manifest Annotations

@Header @Headers
@Capability @Capabilities
@Requirement @Requirements
@Attribute @Directive
@Requirement.Resolution @Requirement.Cardinality
@Export @Export.Substitution

• Arbitrary headers

  @Headers({
    @Header(name = "X-FooHeader", value = "foo"),
    @Header(name = "X-FumHeader", value = "fum")
  })
  public @interface MyHeaders {}
  

• User defined manifest header meta-annotations:

  @Capability(namespace = "my.namespace")
  public @interface MyCapability {
    @Attribute("attr") String value();
  }
  

  @MyCapability("foo")
  public MyClass {}
  

101 Log Service

• Logging API: Logger, LoggerFactory, LogLevel

  @Reference
  LoggerFactory loggerFactory;
  Logger logger = loggerFactory.getLogger(Bar.class);
  logger.error("Seems {} has erred", foo, exception);
  

• Streaming log handler: LogStreamProvider

  @Reference
  LogStreamProvider logStreamProvider;
  logStreamProvider.createStream()
  .forEach(l -> System.out.println(l))
  .onResolve(() -> System.out.println("stream closed"));
  

• Logging configuration: LoggerAdmin, LoggerContext: declarative and programmatic configuration

  @Reference
  LoggerAdmin loggerAdmin;
  loggerAdmin.getLoggerContext("com.foo.bar").setLogLevels(...);
  

• example configuration for PID org.osgi.service.log.admin|com.foo.bar:

  com.foo.bar.Impl=DEBUG
  

104 Configuration Admin Service

• Named factory instances, read-only, passive update, pre-processed configurations

  Configuration c = configurationAdmin.getFactoryConfiguration(
    factoryPid, name, "?");
  c.addAttributes(ConfigurationAttribute.READ_ONLY);
  c.updateIfDifferent(properties);
  Dictionary<String,Object> d = c.getProcessedProperties(
    ServiceReference<?> reference);
  

112 Declarative Services

• Activation/constructor injection

  @Activate
  public Foo(@Reference Bar bar) {...}
  @Activate
  void activate(Config config, @Reference Bar bar) {...}
  

• Logger support

  @Reference
  Logger logger;
  

• Factory properties

  @Component(
    factoryProperties="OSGI-INF/factory.properties",
    factoryProperty="hours:Integer=24"
  )
  

• Detect change to runtime via service.changecount runtime service property

  @Reference(name = "src", updated = "set")
  void set(ServiceComponentRuntime scr){...}
  

• Component property types

  @ComponentPropertyType
  public @interface Config {
  boolean enabled() default true;
  String[] names() default {"a", "b"};
  }
  @Component
  @Config(names="myapp")
  @ServiceRanking(100)
  public class MyComponent {
    @Activate void activate(Config config) {...}
  }
  

Added support for JPA 2.1

• Standard configuration properties
• Updated configuration lifecycle rules
• New EntityManagerFactoryBuilder methods

  String n = entityManagerFactoryBuilder
    .getPersistenceProviderName();
  Bundle b = entityManagerFactoryBuilder
    .getPersistenceProviderBundle();
  

136 Resolver Service

• Define resolution of fragments

  Collection<Resource> rs = resolveContext.findRelatedResources(resource);
  

• Define substitution wires

  List<Wire> ws = resolveContext.getSubstitutionWires(wiring);
  

• Cancelable resolution callback

  resolveContext.onCancel(() -> {/* do something */});
  

• Define dynamic resolving

  resolver.resolveDynamic(resolveContext, wiring, requirement);
  

140 Http Whiteboard

• Standard Component property types

  @Component(
    scope = ServiceScope.PROTOTYPE, service = Servlet.class)
  @HttpWhiteboardServletPattern("/as")
  class MyServlet extends HttpServlet {}
  

• Multipart support

  @Component(
    scope = ServiceScope.PROTOTYPE, service = Servlet.class)
  @HttpWhiteboardServletPattern("/as")
  @HttpWhiteboardServletMultipart(maxFileSize = 10000)
  class MyServlet extends HttpServlet {}
  

• Servlet pre-processors, execute before security, filter chain finishSecurity method

  @Component
  @HttpWhiteboardTarget("(foo=bar)")
  class myPP implements Preprocessor {...}
  if (handleSecurity(req, res)) {
    try {/* do filter chain/servlet */
    } finally {
        finishSecurity(req, res);
    }
  }
  

• Detect changes via service.changecount runtime service property

  @Reference(updated = "setHttpServiceRuntime", policy = DYNAMIC, policyOption = GREEDY)
  void setHttpServiceRuntime(HttpServiceRuntime hsr){
    // has changed
  }
  

• HttpService integration

  @Component(
    scope=ServiceScope.PROTOTYPE, service = Filter.class)
  @HttpWhiteboardFilterPattern("/*")
  @HttpWhiteboardContextSelect(
    "(osgi.http.whiteboard.context.httpservice=*)")
  public class MyFilter implements Filter {...}
  

147 Transaction Control Service NEW

• Portable, modular abstraction for Transaction lifecycle management

  final TransactionControl tc;
  final Connection connection;
  @Activate public Messenger(
    @Reference TransactionControl tc,
    @Reference JDBCConnectionProvider provider) {
    this.tc = tc;
    this.connection = provider.getResrouce(control)
  }
  public void addMessage(String message) {
    tc.required(() -> { //start scope
        PreparedStatement ps = connection.prepareStatement(
            "Insert into MESSAGE values ( ? )");
        ps.setString(1, message);
        return ps.executeUpdate();
    }); // end scope
  }
  

• Allow different resource types to be easily used within a Transaction
• Exception handling
• Rollback avoidance
• Multithreading
• Associate resources with scope
• TX lifecycle callbacks
• Enlist resources with TX
• Mark TX for rollback
• Local & XA
• Builder pattern
• Resource providers
• etc.

148 Cluster Information NEW

API for a management agent to discover, list and inspect available nodes in the cluster.

• Property Prefix: osgi.clusterinfo.
• NodeStatus service properties:

  Map<String, Object> m = nodeStatus.getMetrics(names);
  

  • id
  • cluster
  • parent
  • endpoint
  • endpoint.private
  • vendor
  • version
  • country
  • location
  • region
  • zone
  • tags
• FrameworkNodeStatus properties:

  interface FrameworkNodeStatus
    extends FrameworkManager, NodeStatus {}
  
  BundleDTO bdto = frameworkNodeStatus.installBundle(location);
  

  • org.osgi.framework.version
  • org.osgi.framework.processor
  • org.osgi.framework.os_name
  • java.version
  • java.runtime.version
  • java.specification.version
  • java.vm.version

150 Configurator NEW

Feed configurations into Configuration Admin through

• configuration resources, multiple PIDs, multiple
• configuration resources, extender pattern, UTF-8 encoded
• JSON resources, installed via bundles e.g. OSGI-INF/configurator/foo.json:

  {
    // Global Settings
    ":configurator:resource-version" : 1,
    "pid.a": {
        "key": "val",
        "some_number": 123
    },
    "factory.pid.b~name": {
        "a_boolean": true
    }
  }
  

• Ranking, factory configs, typed, binary data, overwrite

  {
    "my.config": {
        "security.enabled": true,
        "public.key:binary" : "/OSGI-INF/files/mykey.pub"
    }
  }
  

• policy, well defined lifecycle, via system property, coordinator -Dconfigurator.initial={"pid.a": {"some_number": 123}} -Dconfigurator.initial=file:/some.json,file:/other.json
• integration, standalone configurations

151 JAX-RS Whiteboard NEW

• Register JAX-RS annotated POJO (resources), Applications,
• Extensions as services, simple collaboration model

  @Component(service = Foo.class)
  @JaxrsName("foo") @JaxrsResource @Path("foo")
  class Foo {
    @GET @Path("{name}")
    public String interrogateSession(
        @PathParam("name") String name,
        @Context HttpServletRequest req) {
  
       HttpSession s = req.getSession();
       return String.valueOf(s.getAttribute(name));
    }
  }
  

• Require extensions, static resources, multiple whiteboards with own endpoints, simplified default applications,

  @Component
  @JaxrsExtensionSelect("(osgi.jaxrs.name=configProvider)")
  

• Detect runtime changes via service.changecount runtime service property:

  @Reference(updated = "setJaxRSServiceRuntime", policy = DYNAMIC, policyOption = GREEDY)
  void setJaxRSServiceRuntime(JaxRSServiceRuntime runtime){
    // has changed
  }
  

705 Promises

• Thrown exceptions in Function and Predicate, timeout/delay, specify executor/scheduledExecutor, support Callback from org.osgi.util.function

  final Promise<String> answer = new Deferred<String>(
    executor, scheduledExecutor
  ).getPromise().delay(1000).timeout(5000).then(
    new Callback() {
        @Override
        public void run() throws Exception {
            System.out.println(answer);
        }
    }
  );
  

706 Push Stream NEW

• Compact pipeline asynchronous tasks on event arrival, circuit breaker, finite streams & back pressure explicit in API signatures, inspired by Java 8 Streams API, independent, generics, lazy, composed by functional steps, mapping, flat mapping, filtering, stateless & stateful intermediate operations

  PushEventSource<Integer> source = ...
  Integer i = new PushStreamProvider().buildStream(source)
    .withPushbackPolicy(LINEAR, 20)
    .withQueuePolicy(FAIL)
    .build()
    .max(Integer::compare)
    .getValue().get();
  

707 Converter NEW

• Make it easy to convert many types to other types, scalars, collections, maps, beans, interfaces and DTOs, no boilerplate conversion code, customized using converter builders, generics, rules

  Converter c = Converters.standardConverter();
  MyEnum e = c.convert(MyOtherEnum.BLUE).to(MyEnum.class);
  BigDecimal bd = c.convert(12345).to(BigDecimal.class);
  long[] la = c.convert(
    Arrays.asList("978", "142")).to(long[].class);
  Map m = Collections.singletonMap("timeout", "700");
  int t = c.convert(m).to(MyInterface.class).timeout();
  Map m = Collections.singletonMap("args", null)
  String[] a1 = c.convert(m).to(MyAnnotation.class).args();