Forem: Dorian D.

Declarative and reproducible environments with colima, nix and k8s

Dorian D. — Tue, 16 Apr 2024 17:56:53 +0000

Motivation
- Why colima and not docker?
Download and install nix
Usage
- How to use this guide
- Commands
- Garbage collection commands
- Important
About nix
- What's nix?
- What were you sayng about isolation?
Container tools: docker, containerd and nerdctl
Advanced usage (optional)
- Lorri + direnv
- Environment isolation
- Run with --pure
- Using a virtual machine
- Installing an OS inside the nix-shell
- Nix user profiles
Improving the development experience
Code repository

Motivation

Having reproducible environments heavily impacts productivity and developer experience. Being able to test on local machines allows developers to "fail fast" and prevent possible bugs or incidents in production environments.
In an attempt to make my life easier I've studied nix combined with container tools like Colima and k8s.

Why colima and not docker?

Colima is a container runtime which can be use to run containers. There is no need to use docker to run container images and since it now requires you to buy a license I thought it would be more accessible to people who can't afford it.

Download and install `nix`

Download and install the nix package manager.

Usage

Before running the commands below make sure you wiped out all your global dependencies.

Here is an example in case you used homebrew:

my-computer:~$ which kubectl
/opt/homebrew/bin/kubernetes-cli
my-computer:~$ brew uninstall kubectl
Uninstalling /opt/homebrew/Cellar/kubernetes-cli/<version>...
my-computer:~$ which colima
/opt/homebrew/bin/colima
my-computer:~$ brew uninstall colima
Uninstalling /opt/homebrew/Cellar/colima/<version>...

If you also have docker installed globally on your machine, you should also uninstall it if you want a clean slate, because in the shell.nix file there is an alias for docker that could mess up your configuration.

Make sure that colima config files are deleted as well (they are usually in the ~ directory under ~/.config/colima).
You can proceed without deleting these dependencies, but global configuration could clash with the local one and some of the commands may not work properly.

There is a way to make this work in any case without uninstalling your global packages, but it's less simple.

How to read this guide

There are commands that you will need to run inside your shell, these are prefixed by my-computer:~/colima-k8s-nix$ assuming you clone this repo in your home directory ~ or /Users/<your-username> on Mac and /users/<your-username> on Linux.

The commands that you need to run in the nix-shell are prefixed with [nix-shell:~/colima-k8s-nix]$ instead.

Commands

Start a nix-shell with colima and k8s:

my-computer:~/colima-k8s-nix$ nix-shell

Inside the shell type:

[nix-shell:~/colima-k8s-nix]$ colima start --cpu 4 --memory 8 --network-address --kubernetes -r containerd

Pulling docker images:

[nix-shell:~/colima-k8s-nix]$ docker pull nginx
[nix-shell:~/colima-k8s-nix]$ docker pull openjdk:alpine
[nix-shell:~/colima-k8s-nix]$ docker pull mongo

Verifying that colima is in kubernetes mode:

[nix-shell:~/colima-k8s-nix]$ kubectl run -i --tty busybox --image=busybox -- sh

Exit from k8s mode: ctrl + d.

Stop colima runtime to free CPU and memory:

[nix-shell:~/colima-k8s-nix]$ colima stop

Delete and tear down colima instances:

[nix-shell:~/colima-k8s-nix]$ colima delete default #colima delete <name-of-the-instance>

Exit from nix-shell by typing:

[nix-shell:~/colima-k8s-nix]$ exit

Garbage collection commands

Nix is really powerful, but in its raw state it generates a lot of garbage. There are some ways to handle this gracefully, but for now just run commands that handle garbage collection.

my-computer:~/colima-k8s-nix$ nix-env --delete-generations old
my-computer:~/colima-k8s-nix$ nix-store --gc
my-computer:~/colima-k8s-nix$ nix-collect-garbage -d

You can also run nix-collect-garbage if you're not sure which packages you should get rid of.

More on nix garbage collection can be found here.

Important

Before leaving the nix-shell make sure that you stopped and deleted all the instances of colima.

In fact although the local dependencies of the shell are separated from the one on your local machine (you can find more about this topic here here) you still share your file system, user groups etc. with the nix-shell. In this way the shell is the closest environment to your local without messing up your installed dependencies. This approach has advantages and disadvantages.

❗❗Please make sure to run the commands to delete colima instances and the garbage collection commands after you're done developing.

About `nix`

What's `nix`?

Nix is a cross-platform package manager. It uses the nix programming language. Nix and NixOs are often used in the same context, but while the first is a package manager, the latter is a linux distribution based on nix.

The nix ecosystem comes with a lot of tools. The nix-shell is one of these. Under the hood it uses the nix packages, aka nixpkgs, which are packages that can be found in this repository.

One of the advantages of using the nix ecosystem is the capacity to make reproducible, declarative and reliable systems. One of the disadvantages is that getting to know this ecosystem can be very overwhelming and therefore it has a steep learning curve when compared to other build tools.

What were you saying about isolation?

So far we know that we can tap in this "magic" shell that has everything that we need without the hassle.

But what is this exactly? Is this a container? Is this a virtual machine? Let's ask our shell to give us some information about our operating system and platform:

my-computer:~/colima-k8s-nix$ uname -a

And now let's ask the nix-shell:

[nix-shell:~/colima-k8s-nix]$ uname -a

You will notice that the answer is exactly the same. This is certainly not what we would obtain if we would run the same command in a docker container or in a virtual machine. So our nix-shell shares ressources with our machine.

What does this mean for us? One of the consequences of this is that when we run commands on this nix-shell (which is configured as in the shell.nix file), it's as if we would install those dependencies on our machine with homebrew for example. This also means that if we create a file from the nix-shell, we will be able to find it if we jump back to our normal shell:

[nix-shell:~/colima-k8s-nix]$ touch test.txt

my-computer:~/colima-k8s-nix$ ls
LICENSE   README.md     shell.nix      test.txt

And the same goes if we first create a file through our regular shell and we want to read it from the nix-shell. So the environment¹ that we have in the nix-shell is closer to our real shell. This is why we have to handle the memory responsibly and use garbage collection commands. The memory that nix uses to download and install packages is the physical memory of our machine, not the virtualized one (like in the case of containers and virtual machines).

This also means that if we exit the shell without stopping and deleting the colima instance that we started, it will continue to run even when we exit the nix-shell and even if we don't have colima installed globally.

Container tools: `docker`, `containerd` and `nerdctl`

You might have noticed that inside the nix-shell we've created the colima instance with the flag -r containerd. In fact if you try to run the same command without the flag you will get this error:

INFO[0000] starting colima
INFO[0000] runtime: docker+k3s
FATA[0000] dependency check failed for docker: docker not found, run 'brew install docker' to install

Why is that? In the shell.nix file we only have colima and kubernetes as dependencies. colima already ships with containerd, which is the same container runtime that docker uses under the hood. So since we are already using colima we don't need to download docker for the runtime.

What about the docker-cli? colima also ships with a docker-compatible cli to interact with containerd called nerdctl. We can execute the same docker cli commands like:

[nix-shell:~/colima-k8s-nix]$ colima nerdctl pull nginx

For brevity and "developer experience" I created a local alias in shell.nix for colima nerdctl which is called docker:

[nix-shell:~/colima-k8s-nix]$ type docker
docker is aliased to `colima nerdctl'

❗❗ Please note that this alias could clash with your global configuration if you have docker installed globally on your machine.

Advanced usage (optional)

This is by no means an exaustive list of how you can customize your builds, deployments and development environments with nix, but just some examples.

`lorri` + `direnv`

lorri is a nix-shell replacement for project development. Once you've downloaded and installed it you can initialize your project like this:

my-computer:~/colima-k8s-nix$ lorri init

This command will also create an .envrc file in which you can configure your shell. Then you can run:

my-computer:~/colima-k8s-nix$ lorri deamon

lorri's deamon gives you information about your shell, takes care of the garbage collection for you and "watches" your shell.nix files for changes, so you don't need to reload the shell if you add a dependency. Neat!

Moreover lorri works together with direnv.

One downside of using nix-shell is that you can only use bash inside of it. Instead when using lorri in the newly created .envrc file you can define other shells like zsh or fish, thanks to lorri's integration with direnv.

Environment isolation

Run with `--pure`

When you run the nix-shell, it inherits your global configuration by default. If you don't want the already installed packages to affect your development and productivity, you can run:

my-computer:~/colima-k8s-nix$ nix-shell --pure

The pure flag gives you a clean slate. But in this case the nix-shell will only have installed the packages that are specified in shell.nix. So for example in a nix-shell --pure:

[nix-shell:~/colima-k8s-nix]$ ls 
bash: ls: command not found

So if you will need ls or other commands that come with your Unix operating system, you will have to specify them in the shell.nix file together with the other packages:

[...]

  buildInputs = with pkgs.buildPackages; [
    ls
    colima
    kubectl
  ];

[...]

Using a `virtual machine`

You can run a virtual machine (e.g. lima) from inside a nix-shell, exactly as you would do with a regular shell.

In this case lima will provide with the level of isolation that nix-shell lacks when we don't pass the pure flag. In this case the control is relinquished to the virtual machine, so e.g. lima can't write by default in the ~ folder, but provides an isolated folder in which it has both reading and writing rights.

Installing an OS inside the shell

Although this is a different approach with respect to using an already existing virtual machine, we can achieve similar results in terms of isolation and to which we can do inside the shell (for example combined with the pure flag).

It goes without saying, that you can download the NixOs linux distro within your nix-shell. But you can install other operating systems as well, like you would do in a container or virtual machine.

So as you can see, this is the power of nix, we started from a simple package management problem and incrementally we are building a virual machine in a declarative way. Simply amazing!

This is an example of how nix-shell allows you to create ephemeral environments. Check this video if you want to know more.

`nix` user profiles

Let's put aside the level of isolation that a virtual machine guarantees for a moment.

Another possibility to partially isolate in nix is using user profiles. If you have multiple users in your machine you can switch between them and also give root priviledges to any user for whatever specific action. In this case, without additional isolation though, you can affect existing users on your machine.

Improving the development experience

With a few tweaks we can improve our development experience.

Automatic environments
Improving reproducibility

Code repository

Article originally posted on github.

I'm using this term loosely here, not necessarily related to nix-env which is a concept and tool of its own. ↩

Hacktoberfest for the busy developer

Dorian D. — Fri, 07 Oct 2022 17:26:42 +0000

If you have never contributed to open source, Hacktoberfest is the perfect chance for you.
There are plenty of guides for beginners. This is a guide for those developers with some industry experience - but no open source experience - who have a day job and other obligations.

The goal of this guide is to optimize your time as first time contributor and let you focus on the fun part: coding and collaborating with other people on open source projects.
Contributing to open source doesn't always benefit from all the organization of labor and the structure that you have at work. You can easily waste a lot of time to find the right projects or to setup your local environment or even waiting for a review of your PR that never comes.
This can be very frustrating and make you give up altogether. It doesn't have to be like that. I hope this guide will help you to make the best out of the Hacktoberfest.

This guide will refer to GitHub projects only, but with few modifications you can use it to contribute to projects on GitLab.

Step 1: register to the event
Step 2: find the right projects
Step 3: evaluate a project
Step 4: start contributing
Final considerations

Step 1: register to the event

Step 2: Find the right projects

Discord

If you joined the discord Hacktoberfest server you can find some projects here.

The good thing of finding a project through discord is that you can communicate directly with the project maintainer.

To search for a project written in your favorite language just use the bar at the top right of the screen:

GitHub

I find the GitHub issue tracker very helpful. When you visit this page you will probably find only the issues you created.

This is because the default filters are as follows:

is:open is:issue author:yourgithubusername archived:false

Let's modify the filters to get more appropriate results.
First of all you want to get rid of the author filter.

This is more like it. But the list of issues is still too broad and not so much use.
Now let's say I want to find the Hacktoberfest issues that require as language Kotlin:

The filters that we've applied now look like this:
is:open is:issue archived:false label:hacktoberfest language:kotlin

By default the result are sorted by newest issue. You can change the order by clicking on the Sort dropdown menu. This is a particular that will be more important in the next section of the guide: evaluate a project.

Step 3: evaluate a project

Now that we have a list of possible results, let's see some strategies to find the best project to work on in the least amount of time.

If you found project through GitHub, before visiting every single repo/issue that might have caught your attention there are two important considerations:

1) the programming language might not be a sufficient filter criteria. Different languages can be used by very different frameworks/platform/etc. E.g. A Kotlin Developer might not have extensive experience with Android development. If you found your project through Discord, you probably had the chance to do your own filtering. But if you found your projects on GitHub, sometimes you can get this information directly from the list of issues, by hovering over the repo name:

2) the sorting criteria is very important. You want to have the newest or most recently updated issues. If the issue is new or has been updated recently it means that the repository maintainer is active and/or has interest to find people to fix the issue. This can speed up the review process and make it so, that your PR is more likely to be accepted in time.

Now that we have clarified these two aspects, let's talk about what to look for in the repository itself and how to evaluate the issue.

What to look for in the repository

Documentation

Before being a contributor you'll be a user. A good project has to have some basic user documentation. In smaller projects it's usually in the README.md file, but some projects automatically build the docs from the source, so you might have to visit another website to get more details.
This is the minimum requirement for you even consider this project. You have to be able to run this project on your local environment to be able to test your changes.

When was the last commit

If you got this project from GitHub and followed the relative section you probably don't need this. Checking for the date of the last commit, gives you an idea on if the project is still "alive" and how active are the maintainers.

Domain and complexity

There are repositories that have active maintainers and are well documented, however it can require some time to understand the domain logic (like what's this project about) and tackle the complexity (the repository has multiple independent packages, the project has a lot of features, etc.). The fact that this requires you to do some reading shouldn't discourage you from contributing. However if you decide to contribute to a more complex project consider this 3 things:
1) How interested are you in the domain? You have more chances to be successful if you don't feel reading the documentation like a burden.
2) How many issues in the same project can you start contributing to? Even if you're really interested, you have to consider that all that reading will require time. At some point you will want to get started coding. If there are no issues for beginners (usually labeled as low-hanging-fruit, good-first-issue, up-for-grabs, etc.) you risk spending too much time on just one issue, when you could work on smaller projects. It could be still worth your time, if you think you want to continue to contribute long term to this project.
3) How helpful are the maintainers toward beginners? If you start with a complex project, you will probably need to ask questions and clarify things that maintainers and experienced contributors take for granted. Check how issues are explained (more details in the next section) and how maintainers and other contributors answer to questions. Do they give detailed explanation (like exact names of the classes/functions/packages), provide links, refer to the documentations, etc.? Or do newbies often have to ask extra questions because the answer was not accurate enough? These aspects might influence your decision, as you have limited time.

How to understand if the issue is right for you

Ideally by looking at the issue and source code you should be able to have an idea of what's the issue about and vague strategy on how to solve or at least where to start from when looking for a solution.
When looking at an issue make sure to look at the comments as well. Are there already other users that requested to work on it? If yes, you want to skip this issue it doesn't make sense to have two people opening PRs on the same issue.

If the issue is a feature request

The issue should have clearly defined expectations, possibly provide example(s) of expected outcomes and the name of the class/function/package/file to modify.
If adding this feature will affect other functionalities in a not straightforward way this should be also be accurately described in the issue.

If the issue is a bug

The issue should describe the problematic behavior and what the ideal behavior should look like. Moreover there should be a description as accurate as possible on how to reproduce the bug.

If the issue is an enhancement

The scope shouldn't be too broad or vague. E.g. "Make the application more performant" is a bad scope. There are many ways to do that and this kind of scope invites to a discussion which might end with no decision and no PR on your side.

Step 4: start contributing

When you finally found an issue to work on, make sure to comment it and make the maintainer aware of the fact that you want to work on it.

Read the guidelines to contribute to the project. They are usually in the README.md or CONTRIBUTING.md. If you don't find much information about how to contribute to a specific project, you can follow this list:
1) Fork the project. You will find the "Fork" button at the top right corner of the main project page:

The fork is a copy of the project in your account. You will create your PR from this. If the guidelines require you to checkout from a branch that is not main, make sure to import other branches while forking. Keep in mind that the fork, by default, is out of sync with the relative branch of the original project. If some other pull requests get merged before you're done with yours you will have to sync with the original project and rebase your branch before opening your PR.

You can also automatically sync.

2) Setup your local environment. You should be able to build and run the project locally. Run the tests and see if they are failing. If you have trouble with the setup and there is no information that can help you in the documentation you should probably stop here and look for another project/issue.

3) You probably know this from your work, but in case it needs to be repeated, give your branch a significant recognizable name that points to the issue you're working on.

4) This is also general good advice (but it's even more important in a open source project): write meaningful commit messages. Amend commits if you realized that the message is not good enough. If there is no specification on how to write a good commit message in the contribution guidelines, a good rule is to the name of the branch or issue you're working on at the beginning of the message. E.g. for branch prevent_committing_when_no_changes, a good commit message would be [prevent committing when no changes] added getCommandOutput function. This will make it easier to search the commit history in the future.

5) Testing while coding should give you an immediate feedback if you're going in a right direction. But don't forget to test at the end, to make sure you haven't overseen anything.

6) Write documentation for your code. A good rule of thumb is to follow the documentation style that is already present in the project.

7) Before submitting your PR be your first reviewer. Go once again through your final solution. Read again the issue to make sure that you understood correctly the specifications and didn't miss anything.

8) After submitting the PR if you receive a request from a maintainer try to discuss in a constructive way and don't be defensive about your code (after all we all make mistakes!). Keep in mind that the maintainer is the "architect" of the project and has more knowledge about it.

8) Not being defensive doesn't mean that you can't voice your opinion. Offer your opinion in terms of suggestion and be ready to take for as an answer.

Final considerations

Quantity over quality?

From what discussed above one might think that this guide pushes you to prefer quantity over quality. To successfully participate to the Hacktoberfest you will need 4 PRs merged until the end of October. You might find it rewarding contributing to open source even if you don't achieve this goal. From experience though I found out that having multiple PRs merged in open source projects has given me the confidence to explore more complex projects and I think to become a regular contributor.
I hope this guide helps you in this way.

Maintainers

While contributing keep in mind that maintainers might be "busy developers" too. Writing good documentation, writing good issues and in general maintaining the project takes a considerable amount of time. It's just amazing that people do this for free in their free time. Often maintainers will thank you for the contribution, but you should be thankful as well. As developers we use open source software every day. It is what allows us to build our applications, to learn, to grow, to find new solutions, to innovate. And now you are a part of this!

That's it for this guide!

Happy coding!