{"id":18044587,"url":"https://github.com/nodeshift/kube-service-bindings","last_synced_at":"2025-04-10T01:06:48.849Z","repository":{"id":37037142,"uuid":"357715336","full_name":"nodeshift/kube-service-bindings","owner":"nodeshift","description":"Kubernetes service bindings utility","archived":false,"fork":false,"pushed_at":"2025-04-05T07:59:33.000Z","size":720,"stargazers_count":14,"open_issues_count":2,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-10T01:06:38.403Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodeshift.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-04-13T23:28:52.000Z","updated_at":"2024-08-13T08:00:54.000Z","dependencies_parsed_at":"2024-01-23T18:54:05.461Z","dependency_job_id":"c8068589-8823-431f-bce0-fe28f228f213","html_url":"https://github.com/nodeshift/kube-service-bindings","commit_stats":{"total_commits":111,"total_committers":10,"mean_commits":11.1,"dds":0.6396396396396397,"last_synced_commit":"1a64ad324c5ef183b70105d4524fd38cac0bf4b3"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fkube-service-bindings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fkube-service-bindings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fkube-service-bindings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fkube-service-bindings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodeshift","download_url":"https://codeload.github.com/nodeshift/kube-service-bindings/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137887,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T18:09:27.665Z","updated_at":"2025-04-10T01:06:48.830Z","avatar_url":"https://github.com/nodeshift.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kube-service-bindings\n\nService bindings is [kubernetes](https://kubernetes.io/) spec on\nhow to communicate service secrets to applications in an automated way.\nThe spec is available [here](https://github.com/k8s-service-bindings/spec).\n\nThe goal of this package is to make it easy for Node.js\napplications to consume these secrets, without requiring developers\nto be familiar with service bindings.\n\n![CI](https://github.com/nodeshift/kube-service-bindings/workflows/Node.js%20CI/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/nodeshift/kube-service-bindings/badge.svg?branch=main)](https://coveralls.io/github/nodeshift/kube-service-bindings?branch=main)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![NPM version](https://img.shields.io/npm/v/kube-service-bindings.svg)](https://www.npmjs.com/package/kube-service-bindings)\n\n# Install\n\n```\nnpm install kube-service-bindings --save\n```\n\n# Supported Node.js Versions\n\n**kube-service-bindings** supports and is tested only on the current, maintenance and active [Node.js LTS versions](https://github.com/nodejs/Release#release-schedule). We will bump the major version in a release of kube-service-bindings soon after an LTS version of Node.js goes EOL.\n\n# Usage\n\nThe package provides the `getBinding` method which does roughly\nthe following:\n\n- Looks for the $SERVICE_BINDING_ROOT variable in order\n  to determine if bindings are available.\n- Reads the info from the files.\n- Maps the names of the files to the options names needed by the\n  Node.js clients that will connect to the service.\n\n## getBinding(type, client, bindingOptions)\n\nThis is an example of how kube-service-bindings might be used:\n\n```JavaScript\nconst Kafka = require('node-rdkafka');\nconst serviceBindings = require('kube-service-bindings');\n\ntry {\n  // check if the deployment has been bound to a kafka instance through\n  // service bindings. If so use that connect info\n  kafkaConnectionBindings = serviceBindings.getBinding('KAFKA', 'node-rdkafka');\n} catch (err) { // proper error handling here\n};\n\nconst stream = Kafka.KafkaConsumer.createReadStream(\n  Object.assign({\n    'group.id': 'consumer-test', // identifier to use to help trace activity in Kafka\n    'socket.keepalive.enable': true, // Enable TCP keep-alives on broker sockets\n    'enable.auto.commit': false // Automatically and periodically commit offsets in the background.\n  }, kafkaConnectionBindings),\n  {},\n  {\n    topics: 'countries'\n  }\n);\n```\n\nThe parameters for `getBinding` include:\n\n| Parameter                         | Type     |\n| --------------------------------- | -------- |\n| [type](#type)                     | `String` |\n| [client](#client)                 | `String` |\n| [bindingOptions](#bindingoptions) | `Object` |\n\n### type\n\nThe type of service for which a binding is being\nrequested. Currently the supported types are:\n\n- 'KAFKA'\n- 'POSTGRESQL'\n- 'REDIS'\n- 'MONGODB'\n- 'AMQP'\n- 'MYSQL'\n\n### client\n\nThe package the application is using to connect\nto the service. kube-service-bindings is aware of a\nsubset of possible packages. For those that it is aware\nof, it can map the service bindings into the form\nrequired by the client.\n\nCurrently the following clients are recognized based on the supported types:\n\n- KAFKA\n  - node-rdkafka\n  - kafkajs\n- POSTGRESQL\n  - pg\n  - odbc\n- REDIS\n  - redis\n  - ioredis\n- MONGODB\n  - mongodb\n  - mongoose\n- AMQP\n  - rhea\n- MYSQL\n  - mysql\n  - mysql2\n  - odbc\n\n**(Deprecated)** If you don't specify a client, the object returned will\nbe a direct map from the bindings, with the keys\ncorresponding to the name of each file provided by the\nbinding.\n\n#### Example on mongoDB client\n\n```javascript\nconst serviceBindings = require('kube-service-bindings');\nconst { MongoClient } = require('mongodb');\n\nconst { url, connectionOptions } = serviceBindings.getBinding(\n  'MONGODB',\n  'mongodb'\n);\n\nconst mongoClient = new MongoClient(url, connectionOptions);\n```\n\n### bindingOptions\n\nAn object which provides additional control over how binding data is parsed.\n\n| Attribute                         | type      | default Value |\n| --------------------------------- | --------- | ------------- |\n| [id](#id)                         | `String`  | undefined     |\n| [removeUnmapped](#removeunmapped) | `Boolean` | as set by client, or true if not set by client |\n| [allowCopy](#allowcopy)           | `Boolean` | false         |\n| [bindingData](#bindingdata)       | `Object`  | undefined     |\n\n#### id\n\nId used to filter the available bindings.  For example, if you have two Kafka services bound to your application an id can be specified to identify which one should be used.  If there are multiple bindings that satisfy a request and no id is specified, the first one found will be used.\n\n#### removeUnmapped\n\nRemoves all binding data which is not mapped for the client. If false any binding data which is not mapped remains in it's raw form on the binding object returned.  The default depends on the client.\n\n#### allowCopy\n\nEnables setting proper permissions for some of the binding data, where the system has not provided them correctly. It allows binding files content to be copied/stored in a new file and directory. This has to be enabled by the user in order to be aware of the security risk, as some files might include sensitive material. For example, connecting to postgresql with the odbc client, the following error is thrown  for the tls.key file if copies are not allowed: `permissions should be u=rw (0600) or less`.\n\n#### bindingData\n\nAn optional object for passing binding data to kube-service-bindings. This is useful especially in local dev environtment or as a fallback in case of binding data are not available.\n\nExample 1 mongodb client:\n\n```javascript\nconst serviceBindings = require('kube-service-bindings');\n\nlet url;\nlet connectionOptions;\n\ntry {\n  ({ url, connectionOptions } = serviceBindings.getBinding(\n    'MONGODB',\n    'mongodb'\n  ));\n} catch (err) {\n  ({ url, connectionOptions } = serviceBindings.getBinding(\n    'MONGODB',\n    'mongodb',\n    {\n      host: 'mongodb.host.com',\n      password: 'password',\n      port: 27017,\n      username: 'user1'\n    }\n  ));\n}\n```\n\nExample 2 kafkajs client:\n\n```javascript\nconst serviceBindings = require('kube-service-bindings');\n\nlet kafkaConnectionBindings;\n\ntry {\n  kafkaConnectionBindings = serviceBindings.getBinding('KAFKA', 'kafkajs');\n} catch (err) {\n  kafkaConnectionBindings = serviceBindings.getBinding('KAFKA', 'kafkajs', {\n    bootstrapServers: 'test-boostrap:443',\n    clientId: 'client1',\n    clientSecret: 'pass1',\n    password: 'pass1',\n    provider: 'rhoas',\n    saslMechanism: 'PLAIN',\n    securityProtocol: 'SASL_SSL',\n    type: 'kafka',\n    user: 'user1'\n  });\n}\n```\n\n  \u003c!--\n  | case | Arg1 | Arg2        | Arg3        | Supported | deprecate |\n  | ---- | ---- | ----------- | ----------- | --------- | --------- |\n  | 1    | -    | -           | -           | true      | -         |\n  | 2    | type | -           | -           | true      | true      |\n  | 3    | type | id          | -           | false     |           |\n  | 4    | type | bindOptions | -           | false     |           |\n  | 5    | type | client      | -           | true      | -         |\n  | 6    | type | client      | id          | true      | true      |\n  | 7    | type | client      | bindOptions | true      | -         | --\u003e\n\n## getBinding()\n\nIf you don't specify any parameters the getBinding function will return binding data in raw format.\n\n#### Example of fetching binding data in raw format\n\n```bash\n$ tree $SERVICE_BINDING_ROOT\n\n/bindings\n├── kafka-bindings\n│   ├── bootstrapServers\n│   ├── clientId\n│   ├── clientSecret\n│   ├── password\n│   ├── provider\n│   ├── saslMechanism\n│   ├── securityProtocol\n│   ├── type\n│   └── user\n└── kafka-bindings-another\n    ├── bootstrapServers\n    ├── clientId\n    ├── clientSecret\n    ├── password\n    ├── provider\n    ├── saslMechanism\n    ├── securityProtocol\n    ├── type\n    └── user\n\n```\n\nBy executing getBinding in the above environment.\n\n```javascript\nconst serviceBindings = require('kube-service-bindings');\n\nconst rawBindingData = getBinding();\n\nconsole.log(rawBindingData);\n```\n\nWill result in below output:\n\n```json\n[\n  {\n    \"bootstrapServers\": \"test-boostrap:443\",\n    \"clientId\": \"client1\",\n    \"clientSecret\": \"pass1\",\n    \"password\": \"pass1\",\n    \"provider\": \"rhoas\",\n    \"saslMechanism\": \"PLAIN\",\n    \"securityProtocol\": \"SASL_SSL\",\n    \"type\": \"kafka\",\n    \"user\": \"user1\"\n  },\n  {\n    \"bootstrapServers\": \"another-test-boostrap:443\",\n    \"clientId\": \"another-client1\",\n    \"clientSecret\": \"another-pass1\",\n    \"password\": \"another-pass1\",\n    \"provider\": \"another-rhoas\",\n    \"saslMechanism\": \"another-PLAIN\",\n    \"securityProtocol\": \"another-SASL_SSL\",\n    \"type\": \"another-kafka\",\n    \"user\": \"another-user1\"\n  }\n]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeshift%2Fkube-service-bindings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodeshift%2Fkube-service-bindings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeshift%2Fkube-service-bindings/lists"}